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0: INTRODUCTION 

This document is a guide for users of ee9, a program emulating the EE KDF9 computer. Readers not yet familiar with the 
KDF9 should consult the companion document, The English Electric KDF9; you will will be referred to the ‘Manual’ for 
further details; this is the KDF9 Programming Manual, the nearest thing we have to a definitive reference work. ee9 should 
be portable to any system with a basic POSIX API. It is written in Ada 2012 using the GNU Ada compiler, and is available 
for a range of computers and operating systems. For the characteristics of the latest version, see $6. 


1: USING ee9 CONVENIENTLY 

ee9 can be invoked directly, but it is very much easier to use the command files described in this section. The default setup 
runs them in the directory Testing,so Testing should be in your search path to make them accessible to the shell. That 
is what the immediately following descriptions assume. However, they may be made use of elsewhere so long as you create a 
compatible environment, for which see $3.1, Appendix 1, and the accompanying README file, inter alia. 

ee9 requires KDF9 source code and data files to use the Latin-1 text encoding. When you create such a file, ensure that it is 
saved in the Latin-1 format and not, for example, as UTF-8. The latter would cause characters outside the ASCII subset to be 
saved as UTF-8 byte pairs, which are meaningless to KDF9 software. The terminal window background is assumed by 
default to be of a colour other than black or red. White best matches the look of Flexowriter printout. To work with a dark 
background, or other colours, see Appendix 1. 

The directories, e.g. Binary and Assembly, etc, named in the following, are all subdirectories of Testing. They are 
defaults only; alternative locations for your files may be specified, for which see Appendix 1. 


[9 E 


nine prog [datal - ] [model - ] [miscellany| - ] [tt [tt]] 


nine runs the KDF9 machine code program prog. The executable is taken from Binary /prog; the data for tape reader 1 
(TR1), if specified, is taken from Data/data. txt, failing which from Data/data. A parameter may be given as ‘-’ if it is 
not needed and a later parameter must be specified. All the optional parameters may be omitted, as they default wisely. 


The allowable execution mode characters (see $2.1) are: 
* £: for fast mode, the default (if £ is explicitly specified, the real CPU time for the run is displayed on termination) 
* p: for pause mode 
e t: for trace mode 
* x: for external trace mode 
The allowable characters in the optional miscellany parameter are described in $5.2. 


The parameters ff specify the character codes to be used by either one or two paper tape punches (the first ff), or paper tape 
readers (the second ff). tt is either one or two characters, each being either k/K or 1/L, specifying KDF9 paper tape code or 
Latin-1 code respectively. If tt is one character, it refers to unit O of the type (i.e. TPO or TRO). If tt is two characters, the 
first refers to unit 0 and the second to unit 1 of the type. The default code is Latin-1. See also 83.4 and Appendix 2. 


crnine prog [ data | - ] [model- ] [miscellany |- ] 
crnine is like nine, except that data, if specified, is made available via the punched card reader file, CRO. 


nine priv prog [ data | - ] [model - ] [miscellany| — ] [tt [1t] ] 
nine priv is like nine, but the program is executed in the ‘privileged program’ mode. See $22. 
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tsdnine prog [datal-] [model-] [miscellany|-][tt [ tt] ] 


tsdnine runs a program with data supplied as TR1, under the control of the Time Sharing Director (TSD). The parameters 
are as for nine, except that a data file name without a . txt suffix is taken to be in KDF9 code. Before booting, tsdnine 
ensures that the magnetic tape files have valid labels. See Appendix 9 for a primer on operating the TSD. 


A program run by nine, crnineornine priv, with ee9 emulating the Director's API, is said to be running ‘directly’. 


Machine code programs for execution by ee9 can be created by compiling KDF9 Usercode or Algol source programs. 
Examples can be found in the Testing/Assembly, Testing/Kidsgrove and Testing/Whetstone directories. 


ucc prog 
ucc compiles the KDF9 Usercode program Assembly /prog . k3, placing the object code in Binary /prog; a compilation 
listing is stored in Assembly/prog-listing.txt. For help with KDF9 Usercode see Appendix 13. 


kalgol prog 

kalgol compiles the KDF9 Algol program Kidsgrove/prog.a60, placing the object program in Assembly /prog . k3. 
The latter is then compiled by ucc. The executable left in Binary can be run using nine. The mode and miscellany flags 
for the compiler may be given in the environment variables KIDSMODE and KIDSMISC. By default KTDSMISC-w to 
suppress the compiler's voluminous Flexowriter output. For help with Kidsgrove Algol see Appendix 12. 


kids prog [data | -] [model- ] [miscellany| - ] [tt [tt] ] 
kids compiles and runs Kidsgrove/prog.a60 (using kalgol and then nine). See also wich, in Appendix 12. 


walgol prog [model-] [miscellany |- ] 


walgol compiles and runs the program held in Whetstone/prog.a60 along with any stream 20 input. The file must be 
in Flexowriter format. For more-convenient facilities see whet, following. For help with Whetstone Algol see Appendix 12. 


whet prog [model-] [miscellany |- ] 


whet converts Kidsgrove/prog.a60 from 'stropped' to Flexowriter format, then uses walgol to compile and run it. 
The result may need some amendment to pass compilation by walgol. In particular, unlike kalgol, walgol does not 
implement KDF9 ‘code’ procedures. If the converted file already exists you are asked whether you want to overwrite it. 


stone 
stone runs the Whetstone Benchmark using walgol in authentic timing mode, taking about 7 minutes of real time! 


pasc prog [data | -] [model-] [miscellany| - ] [tt [tt] ] 
pasc compiles and runs Pascal/prog . p (using PASKAL and then glance). See Appendix 14. 


2: EMULATION MODES 
2.1: DIAGNOSTIC MODES 
A KDF9 program is run, at option, in one of four diagnostic modes. These are: 

* fast mode; in which ee9 runs the program at maximum speed, with no execution tracing or interactive diagnostic 

facilities available 

* pause mode, in which ee9 single-shots the program, pausing to interact with the user after each instruction 

* trace mode, in which ee9 runs the program at speed with extensive retrospective tracing enabled 

* external trace mode, in which ee9 writes a summary of every traced instruction to an external file 
More precisely, things work as follows. 
In fast mode ee9 interacts with the user only by providing informative messages, either because the KDF9 program has 
terminated, or to log significant events during the run (such as the allocation of an I/O device). All tracing overhead is 
avoided in fast mode. 
In pause mode ee9 uses console-window text I/O to interact with the user. After each instruction is executed a short summary 
of the machine state is displayed and a prompt asks the user how to continue. The user replies with an optional single letter 
(which may be given in upper case or lower case) followed by RETURN, selecting one of the following: 

e f: execution proceeds in fast mode 

* p: execution proceeds in pause mode 

* t: execution proceeds in trace mode 

* (nothing): execution proceeds in the current mode. 
All retrospective tracing types described in $4 are available in pause mode, trace mode, and external trace mode; but the 
manner of execution depends on whether the current instruction execution lies within a set range of addresses, and within set 


instruction-count bounds. If so, instructions are added to their appropriate traces; and breakpoints and watchpoints are 
monitored. If not, execution proceeds as in fast mode (but at about a third of the speed). 
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2.2: RUN STATES 
The run state specifies how the emulated KDF9 is to run the program: 


* In boot mode the KDF9 reads a 9-word bootstrap routine from TRO, then jumps to word 0, in Director state. 


* [n problem program mode ee9 reads into core, from TRO, a binary program prepared by a compiler. Its execution starts 
at word 0, in program state. ee9 itself implements any OUTs (system calls) requested by the program, so that it is not 
necessary to have a Director running. 


* In privileged program mode ee9 reads and runs a binary program, exactly as in problem program mode, except that 
privileged instructions are allowed to execute successfully instead of failing. 


2.3: BREAKPOINTS, FETCHPOINTS , STOREPOINTS, AND WATCHPOINTS 

Certain addresses in core can be marked as breakpoints or as watchpoints, to force diagnostic interaction with the user. A 
breakpoint is set on an instruction word, and causes interaction after an instruction beginning in that word has been 
executed. A fetchpoint is set on a data word, and causes interaction after data has been fetched from that word. A storepoint 
is set on a data word, and causes interaction after data has been stored into that word. A watchpoint combines a fetchpoint 
and a storepoint on the same word. 


2.4: AUTHENTIC TIMING MODE 

At option, ee9 can be made to insert timed pauses into its execution so that the elapsed time of a program run by ee9 
approximates the elapsed time of a run on the real KDF9 hardware. This may be instructive for younger users, who have 
never seen characters being output by a computer, one at a time, and with noticeable delays! See §5.2. 


3: INPUTS AND OUTPUTS 


3.1: EMULATED KDF9 I/O DEVICES 

At the start of a run ee9 looks in the current directory for files to represent the KDF9 peripherals. There is a fixed assignment 
for the console Flexowriter, which is associated with the user’s interactive terminal window. Other devices are associated 
with files having names derived from the device type. Magnetic tape deck d, for example, is always associated with the file 
named MTd. The full list of these associations is as follows: 


* a card punch is CPd 

* a card reader is CRd 

* a drum store is DRd 

e a fixed disc store is FDd 

* a graph plotter is GPd 

e a line printer is LPd 

e a KDF9 type 1081 magnetic tape deck is MTd 

* a Standard Interface device is SId 

* an IBM-compatible seven-track tape deck is STd 

* a paper tape punch is TPd 

* a paper tape reader is TRd 
Every device file actually used in a run must exist, and be appropriately accessible, when ee9 is invoked. A magnetic tape 
file, if not completely empty, must have a valid label block. (But see RLT in Appendix 11.) The assignment of devices to 
buffers (KDF9 DMA channels) is set by default, but can be changed by the user: see the K option in $5.1. 
3.2: THE FLEXOWRITER CONSOLE TYPEWRITER 
The terminal window is the means by which users, in their róle as KDF9 operators, can mimic Flexowriter I/O. The 
Flexowriter is used to type-in responses to prompts output by problem programs or by Director. Repeatedly typing these 
responses quickly becomes tedious. If a file named FWO exists, it is used as a source of "canned" responses. They are 
defined, with their identifying prompts, in FWO; and are picked up automatically by ee9. If a prompt spreads over more than 
one line, a KDF9 Line Shift can be represented in FWO by a ‘®’, and a KDF9 Page Change by a ‘©’. 


When a prompt is issued, ee9 scans FWO, down from the last match found. If it finds a new match, it injects the given 
response into the Flexowriter input stream; but if it reaches the end of the file without finding a match, it returns control of 
the Flexowriter to the user's terminal window, so that a manual response can be given. If a prompt matches a line in FWO that 
specifies a null response string (c.f. the second ‘OUT;’ in the following example) then ee9 terminates the run. 

For example, the Whetstone Algol compiler prompts ‘[q] OUT;' to which a typical reply is ‘N. |’. If the Algol program 
compiles, it runs and prompts ‘ [q] STREAM;' to which a typical reply is *30. |’; but if the compilation fails the compiler 
loops back to its [q] OUT;' prompt, where the user will normally want to terminate the run so that the Algol source code 
can be amended. The following data in FWO will achieve this without user intervention: 

[q] OUT;N. 
[q] STREAM;30. 
[q] OUT; 

For a second example, as the Time Sharing Director bootstraps it issues a series of requests for basic configuration 
parameters. The following data in FWO supplies suitable responses without user intervention: 


CORE MODULES;8. 
OUT 8 REEL NO;9. 
LEVELS;N. | 

DATE D/M/Y;4/5/67. | 

TIME ON 24-HOUR CLOCK®HOURS/MINS;1/23. 
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This facility had a real equivalent: the Flexowriter incorporated an ‘edge-punched card’ reader. It read data (in paper tape 
code) from the edge of a non-standard punched card. Cards prepared with replies to prompts could be inserted into the reader 
and read at the maximum rate, thus speeding input and avoiding any delay due to typing errors by the operator. 


Note that ee9 requires every Flexowriter input string to be terminated by a RETURN, even when a read-to-End Message 
instruction is being obeyed. In reality, KDF9 would end the transfer immediately at the End Message (EM) character, or 
when the required number of characters had been read; but data is not transferred to ee9’s input buffer until a RETURN is 
typed. A merely terminating RETURN is discarded from the input by ee9, and is not passed to the KDF9 program. 


In response to CTRL-C, ee9 outputs a prompt that lets the diagnostic mode be changed. Replying with RETURN causes a 
FLEX interrupt when running Director, evoking a ‘TINT;’. (CTRL-C typed when ee9 has failed to respond quits the run.) 
Output to the Flexowriter was typed in red; input from the computer operators in black. This is simulated in ee9 by using 


ANSI-standard SGR escape sequences to vary the displayed font style. Some Windows terminal utilities do not implement 
SGR escape sequences, so Flexowriter output styling can be disabled with a miscellany parameter or a settings file option. 


3.3: READING MORE THAN ONE ROLL OF PAPER TAPE OR DECK OF CARDS 

A means is provided to simulate the way in which KDF9’s computer operators could satisfy a program's demand for data 

with several physically-separate rolls of paper tape or decks of cards, loaded into a reader in succession. If a program 

attempts to read from a tape reader, and the end of the associated file has been reached, ee9 allows the user to specify a 

successor file to which the tape reader is re-attached. A prompt requesting more data is displayed. 

* If the user responds ‘=’ then the reader is connected to the user's terminal so that the data may be typed then and there. 

e [f the user responds */' then the pathname of a file supplying the next “roll of tape" may be typed. If the response is ‘@’ 
then the name of a file within the directory specified by KDF9 DATA may be typed; see Appendix 1. With both ‘/’ and ‘@’ 
a final ‘. txt’ may be omitted from the name. If the specified file is not found, or not readable, the prompt is repeated. 

* The filename may be given on the same line as ‘/’ or ‘@’ if the latter is followed by a separator such as a space. 

* [f the user responds ‘q’ or ‘Q’ then execution terminates. 

* [f the user presses RETURN (only), or signals end-of-data (e.g. by typing ^D), the buffer is set to the abnormal state. 
Attempting another read without clearing the error will cause a Lock-In Violation. 

e The foregoing also applies, mutatis mutandis, to punched card readers. 

* See the N option in $5, about disabling this feature in non-interactive mode. 


Examples (user's responses in green): 


1. 

ee9: Type @ or / to name a file, = to type the data, ENTER key for EOF, Q or q to quit: = 
ee9: Type the data for TRI: 
3;| 

2. 

ee9: Type @ or / to name a file, = to type the data, ENTER key for EOF, Q or q to quit: / 
ee9: Give the pathname of the file: next 

The KDF9 operator must have made a mistake: next cannot be read. 


3. 
ee9: Type @ or / to name a file, = to type the data, ENTER key for EOF, Q or q to quit: / Data/next 
4. 


ee9: Type @ or / to name a file, = to type the data, ENTER key for EOF, Q or q to quit: @ 
ee9: Give the name of a file in Data/: next 


5. 
ee9: Type @ or / to name a file, = to type the data, ENTER key for EOF, Q or q to quit: q 


Final State: Run stopped by the user: quit requested. 


3.4: REPRESENTING THE KDF9 CHARACTER SETS 

The KDF9 had its own, somewhat idiosyncratic, character sets. They are tabulated in Appendix 2a. For the convenience of 
the user, external data read and written by the paper tape readers and punches may be represented in either KDF9 paper tape 
code, or in the ISO Latin-1 character set with automatic conversion between Latin-1 and KDF9 codes. Several characters in 
the KDF9 paper tape set are absent from Latin-1, so a simple transliteration is used to represent them externally. 


For the Flexowriter, and for Latin-1 I/O with tape punches and tape readers, Case Normal and Case Shift characters are 
generated on input, and interpreted on output. This means that when you are typing an input text, it is not necessary to type 
Case Normal and Case Shift characters, although there usually is no harm in doing so. When such a text is being read as the 
input stream for a two-shift device, an appropriate case-character is generated automatically by the emulator, if the Latin-1 
character being read is not available in the input device's current shift state. Two-shift output works in the complementary 
manner. Two-shift devices always start out in the Case Normal condition. 


For example, the external Latin-l string ‘Bill Findlay’ may be read into the KDF9 core store as the characters 
‘BBILL NFBINDLAY’, with B denoting the Case Shift character and ñ denoting the Case Normal character. A KDF9 
program that writes the characters ‘BBILL fAFBINDLAY’ to a two-shift device in Latin-1 mode will generate the Latin-1 
string “Bill Findlay’ as its external representation. 


Text-file input to ee9 may use any of CR, LF, or a CRLF pair as the line terminator: ee9 treats all three the same. Text-file 
output from ee9 writes the line terminator most appropriate for the host’s operating system. 


Non-graphic KDF9 characters also have Latin-1 external representations, to enable 1-to-1 inter-conversion between the 
internal and external data formats. Apart from the format effectors (Horizontal Tab, New Line, Form Feed), users should 
never need to type these characters, as they could not be typed on a Flexowriter. 


In KDF9 mode, characters are transmitted using the KDF9 paper tape format, in which devices use an 8-bit byte externally, 
supplementing the 6 internal data bits with two ‘parity’ bits (see also the Manual, §17.4 and Appendix 2b). 


KDF9 object programs are never given in Latin-1, but always natively, in the KDF9 paper tape code. 
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Characters displayed in tracing output are shown using their Case Normal Latin-1 transliterations, except as follows: 
* the KDF9 Horizontal Tab character is depicted as 7 


* the KDF9 Line Shift or LS character (Carriage Return) is depicted as & 


* the KDF9 Page Change or PC character (Form Feed) is depicted as © 
* the KDF9 Filler character is depicted as @ 


These depictions are also used by the card reader and card punch. Card images of less than 80 characters are padded with 
blanks to fill all 80 columns; any input line longer than a card is truncated to 80 characters. In *direct' mode, card images may 
have up to 160 characters, notionally two per card column. The card punch writes files that are valid as input to the card 
reader and can be read to exactly reproduce the original data in core. 


The representation of magnetic tapes is described in detail in Appendix 10. 


Drums and disc drives are represented as plain POSIX files using the Latin-1 Case Normal transliteration. Sector boundaries 
are not explicitly represented: they are implicit in the data address within the POSIX file, occurring every 320 bytes for disc 
drives and every 1024 bytes for drums. 


3.5: GRAPH PLOTTING 

ee9 includes an emulation of the model 564 Calcomp graph plotter, as described in Appendix 6, $5, p.302 of the Manual (but 
see what I say about this in $6: Caveats, and in Appendix 3). There was provision on the KDF9 to switch a buffer manually 
between a tape punch and a graph plotter; in ee9 this is done with g in the miscellany parameter, with a settings file option G, 
or with a settings file option K. When one or more of these is given, GPO replaces TP1 on the shared buffer. 


The KDF9 graph plotter takes commands that move the plotting position in steps of 0.005 inches; see Appendix 3 for the 
command codes. Steps are accumulated into vectors by ee9, and PostScript vector drawing commands are output to GPO, 
creating an Encapsulated PostScript (EPS) file. It is possible to fit the plotter with ‘pens’ having a variety of ink colour and 
ball-point tip size: see under G in $5. 


4: LOGGING AND TRACING 

Messages that record the progress of the emulation, and details of any errors that were detected, are written to the interactive 
console window, along with interactive diagnostics, and output produced for the KDF9 Flexowriter. A selection of these 
messages is also written to the file KDF9 log.txt. On completion of a run, the final machine state, any requested core 
store areas, and any retrospective traces may be written to the log file and to the console window. 


It is possible to request the output of certain areas of the KDF9’s core store, in a variety of suitable formats. These printouts 
can be taken either before the start of execution; or on termination; or at both times, to allow comparisons. 


In the interrupt trace, which is produced only in boot mode, interrupt requests are listed with the privilege state and priority 
of the interrupting device; the elapsed time of occurrence (in ys); and the value of ICR, the Instruction Count Register, which 
is a count of the number of instructions executed so far. The interrupt trace also logs EXITD, return from interrupt, 
instructions. 


The tracing of executed instructions is subject to instruction-count and address-range bounds. Instruction executions within 
those bounds are traced; those that fall outside the bounds are not. 


In the peripheral I/O trace, the events shown are transfer initiations and terminations, busy-buffer and store-access lockouts, 
and I/O status test operations. Each is listed with the device name, Q-store parameter, privilege state (P-S for problem 
program slots and D for Director state) and priority of the transfer; the elapsed time of occurrence of the event; and the 
current instruction count. 


The C part of the parameter used in a disc seek operation is logged in the format DdPppSss, where d, pp and ss are, 
respectively, the drive number, platter number and seek area number being addressed. In non-seek disc operations the C part 
is shown as Sss, where ss is the starting sector number for the transfer. 


The C part of the parameter used in a drum transfer is logged in the format DdTttSs where d, tt and s are the drive number, 
track number and the starting sector number. 


Transfer operations appear twice, once for the initiation (S) and once for the termination (E). Lockouts appear once, when 
they happen. A test operation gives the result of the test as a Boolean (Y or N) in the T field of a trace. 


In the retrospective trace, instructions are listed in order, starting with the most recently executed. The trace includes the 
instruction itself, and its most relevant operand; ‘ND’ and ‘SD’, the Nest and SJNS Depths; ‘V’ and/or ‘T’ showing whether 
overflow and/or the test register is set; the CPU time of occurrence of the event; and the value the current instruction count. 
In the case of a store order, the traced operand is the value written to store. In the case of a fetch order, it is the value fetched. 
For a Q-store order, it is the content of the relevant Q register. For a conditional jump it is the determining value. For 
subroutine jump or exit, it is the relevant value in the SJNS. For a 1-syllable or 2-syllable ALU order, it is the value left in the 
top of the nest. And so on. 


External trace mode is like retrospective mode, with additional output to the file trace. txt. This output has one line for 
each traced instruction. It contains: the instruction's address; the value of ICR; the CPU time; the nest depth; the SJNS depth; 
‘V’ and/or ‘T’ if overflow and/or the test register is set; the value in N1, if the nest if non-empty; and the disassembled 
instruction. 


When tracing, and if requested, ee9 will tally the number of traced executions of each type of KDF9 instruction. On 
termination of a run a histogram of dynamic instruction-type frequencies may be logged. A similar plot may be produced 
showing the frequency with which each instruction-containing word is executed. 


At option, all tracing modes can compute a digital signature of the execution: a 48-bit cumulative hash, displayed in octal, of 
the contents of all the relevant KDF9 registers (nest, SJNS and Q stores) at the end of each traced instruction. Known values 
for this hash can be used to verify the proper operation of an implementation of ee9. (When the signature is enabled, the 
starting time-of-day is forced to midnight, to ensure a repeatable hash value.) 


For examples of the output that can be obtained using these facilities, see Appendices 7A-7G. 
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5: THE MODE SETTINGS FILES AND THE MISCELLANY PARAMETER 
The emulator has default settings for all of its options, but they may be over-ridden by settings specified in files that the 
emulator attempts to read as part of its initialization, and/or by specifying a miscellany parameter on the command line. 


5.1: SETTINGS FILES 

The file settings _1.txt applies to a first or sole program to be run, and settings 2.txt applies to a second 
program overlaid by it (e.g. the Whetstone Controller, overlaid after a successful compilation by the Translator). A setting 
specified by the command line over-rides a similar option specified in the settings 1l.txt file. 


The settings files contain a line for each option to be set, beginning with a letter that specifies the option concerned. This may 
be followed by one or two parameters. Numbers may be given in octal — preceded by a hash sign (‘#’)—or in decimal; and 
this convention is also used systematically in output messages from the emulator. The options are presented here in upper 
case, but lower/mixed case is also accepted. The available options are as follows: 


A MODERN TIMES MODE |AUTHENTIC TIME MODE 


The A flag sets aspects of the AUTHENTICITY of execution. It takes one symbolic parameter. It is possible to set authentic 
elapsed timing (see $2.4), with the AUTHENTIC TIME MODE parameter; in MODERN TIMES MODE emulation proceeds 
at the full speed of the host computer. 


B start [ end ] 


This flag has either one or two parameters, which are instruction-word addresses. It sets a BREAKPOINT on every instruction 
word in the given range of addresses. 


CIA 
This flag is used to set two COUNT values, say / and h, that determine when tracing is done. No breakpoint or watchpoint 
fires, and no instruction is traced, unless l x i < h is satisfied; where i is the current value of ICR. With suitable / and h values, 


tracing can confined to a set time during execution (for example, the last few instruction executions before a program fails). 
The values / and A are given as unsigned decimal integers. 


D FAST MODE|TRACE MODE | PAUSE MODE | EXTERNAL MODE 
This flag sets the DIAGNOSTIC mode, specifying the type of tracing and the kind of logging that may be generated. 


Fi start end [base] and Ii start end [base] 

These flags have two mandatory parameters, which are word addresses. They request that the contents of that range of 
addresses be output in a specified interpretation, INITIALLY, or FINALLY (i.e. after the end of the run). 

For both Ii and Fi, the interpretation is given by the string of letters i, each letter of which must be one of: A, for strings in 
ASCII/LATIN-1 code; C, for strings in card code; L, for strings in LINEPRINTER code; N, for strings in paper tape code, with 
case NORMAL shown; S, for strings in paper tape code, with case SHIFT shown; T, for strings in paper TAPE code, with shift 
characters actioned; O, for syllabic OCTAL/ ORDERS; U, for orders in an approximation to USERCODE format; and W, for data 
WORDS in octal, syllabic octal, line printer characters, Q store format, and signed decimal. 


With U, D can also be given to get machine code addresses in DECIMAL instead of octal. A third parameters may be given. 
When printing the code of a Director it specifies an additional point of entry (e.g. for an overlay). For a problem program it 
specifies the address of VO of the routine delimited by start and end, so that disassembly may present data accesses as V 
store references instead of absolute addresses. For examples of Usercode format, see Appendix 6. 


The PIC, PID, POC and POD instructions for cards and paper tape permit the processing of data in arbitrary character codes. 
The A format for core-store printing is provided to facilitate the debugging of modern KDF9 programs that process data in 
ASCII/Latin-1, the native character set of ee9. 


G [colour [tip size] ] 

This flag allows one or two optional symbolic parameters. The first, if given, sets the GRAPH PLOTTING pen colour from the 
list: BLACK (the default), BLUE, BROWN, CYAN, DARK BLUE, DARK CYAN, DARK GREEN, DARK GREY, 
DARK MAGENTA, DARK RED, GREEN, GREY, MAGENTA, RED, WHITE, YELLOW. If a colour is given, a second parameter 
may be given to set the pen tip size from the list: EXTRA EXTRA FINE (the default, 1 plotter step wide), EXTRA FINE (2 
steps wide), FINE (4 steps), MEDIUM (6), MEDIUM BROAD (8), BROAD (10), EXTRA BROAD (12). 


In any case, the shared buffer is switched from TP1 to GPO. 


Hh cutoff% 

In tracing mode, ee9 collects statistics on the execution of the KDF9 program. These may be displayed at the end of a run in 
the form of histograms. Two plots are available. If ^ contains P or p, an execution-frequency profile is output. If ^ contains T 
or t, then an instruction type frequency histogram is output. Both may be requested. cutoff is a number in the range 0.0 to 
100 0, taken to be a percentage; the % is required to follow the number immediately. Histogram bins that account for less than 
that fraction of all executed instructions are suppressed. Nothing is output if the option is suppressed by the miscellany 
parameter. 


K ( buffer code | 

This flag sets the KDF9 configuration by specifying the device types connected to the buffers. The parameters consist of one 
or more pairs of items, the first a buffer number (in the range 0 to 15) and the second a two-letter code, being the first two 
letters of the device name (e.g. CR or LP). GP may be specified to switch TP1’s buffer to GPO. At most 1 DR unit, 1 FD unit, 
2 TP, TR, CP, CR, LP, or SI units, at most 14 tape decks of either kind, and only one of either DR or FD can be configured. 
To leave a buffer with an absent device, specify the code AD; any attempt to use that buffer will fail. Every configuration 
must have FW on buffer 0 and TR on buffer 1. Any buffer not listed keeps its default device, which is that specified by: 


K 0O FW 1 TR 2 TR 3 TP 4 TP 5 LP 6 CR 7 CP 8 MT 9 MT 10 MT 11 MT 12 MT 13 MT 14 FD 15 ST 


The K flag is actioned only at the start of a run; any K options in the settings 2.txt file are ignored. N.B. The commands 
described in $1 may not work properly with a non-default configuration, especially if only one TR and no TP or LP is included. 
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L[t] 


This flag gives a value, t, that sets an execution time LIMIT on how long the KDF9 program is allowed to execute before 
being terminated. The limit is specified in instruction executions, so the program is terminated if ICR » f at the end of any 
instruction execution. The value f is given as an unsigned decimal integer. If the L flag is given without a parameter the time 
limit is taken to be the default time limit for non-interactive mode (see $6). 


N[t] 

The N flag has one optional parameter, with the same meaning at the t parameter of the L flag. It makes ee9 run in NON- 
INTERACTIVE mode, suitable for invocation from a command script. In this mode it is not possible to supply responses to 
prompts, whether from the KDF9 program or from ee9 itself; so if an interactive input is requested in non-interactive mode, 
ee9 terminates with a suitable diagnostic message. If the N flag is given without a parameter, or on the command line, the 
time limit is taken to be the default time limit for non-interactive mode (see $6). 


(0) 
The O flag outputs the diagnostics (post-run dumps, histograms and traces) requested in settings l.txt when a 
program terminates and nominates an overlaid successor by means of OUT 1 or OUT 2. 


P address value 


This flag is used to POKE the value (given in octal or decimal) into the address. The address takes the form of an octal or 
decimal number, immediately followed by one of the letters W, U, L, S or C. If W is specified, the value overwrites the whole 
word at the address. If U or L is given, the value overwrites the specified halfword. If S or C is given, it must be followed by 
the position within the word of the syllable or character, respectively, to be overwritten. If a part-word is specified, the value 
must be within its storable range. 


Q 


The Q flag outputs any specified pre-run dumps and then quits. It is useful for getting a disassembly of a program without 
running it. 

Ra b 

This flag is used to set two addresses, say a and b, that delimit the RANGE of instructions where tracing is done. No 
breakpoint or watchpoint fires, and no instruction is traced, unless a < i < b is satisfied; where i is the address of the word 
containing the instruction to be executed. With suitable a and b values, instruction tracing can confined to the sequence of 
instructions that you are currently debugging. 

S start [ end ] 

This flag has either one or two parameters, which are data-word addresses. It sets a STOREPOINT on every word in the given 
range of addresses. 

T BOOT_MODE | PROGRAM_MODE | PRIVILEGED_MODE 

This flag is used to set the run state. 

V{ABCDEFHIKPRSTWZ} 


The V flag is used to set the VISIBILITY of diagnostic output. Spaces and tabs after the V are ignored. It is immediately 
followed by a selection of the letters: A to suppress Director API messages, E to suppress confirmatory or warning messages 
— but not error messages — from ee9, F to suppress the FINAL STATE of the KDF9 at the end of a run, H for the HISTOGRAMS, 
I for the INTERRUPT trace, P for the PERIPHERAL I/O trace, R for the RETRO trace, S for the digital SIGNATURE, W for console 
Flexowriter output, and Z for all inessential output. A trace is output if it is provided by the requested diagnostic mode, and 
its output is not suppressed. The default is that all traces provided by the diagnostic mode are to be output, i.e. not 
suppressed. V by itself restores the default options. 


The option B installs the BSI interface, SIO, on buffer 15/717. 

The option C enables the output of a Core image file in the event of abnormal termination. 
The option D enables the output of any optional Debugging messages. 

The option K installs the drum, DRO, on buffer 14/716. 

The option T enables execution with authentic TIMING (see $2.4). 


W start [ end ] 

This flag has either one or two parameters, which are data-word addresses. It sets a WATCHPOINT (i.e., a FETCHPOINT and a 
STOREPOINT) on every word in the given range of addresses. Note that it is not possible to set a FETCHPOINT only. 

X 

The X flag over-rides other diagnostic options and runs the program in external tracing mode with only signature generation 
enabled. 

Y 

The Y flag sets up an operand symbol table entry to be used when disassembling orders during tracing and when printing 
Usercode format core dumps. Y by itself clears out the symbol table. See Appendix 6 for a full description of this feature. 
/|- 

A line beginning with / or with — is taken to be comment and ignored. 

5.2: THE MISCELLANY PARAMETER 

The options permitted with the miscellany parameter on the command line are as follows: 


abcdefghiknopqrstwxyz.0123456789- 


The miscellany parameter is put into effect from left to right; it is case-insensitive. The letters gnoqx correspond to the 
option flags of the same name, with the defaults stated in $5.1 for their parameters. The letters abcdefhikprstw 
correspond to the options that can be given with the V flag, as defined in $5.1. A digit d requests an execution time limit of 
(d--1)x100. 000 000 instructions; ‘.’ specifies a time limit of 1 000. 000. Option y specifies that the program is to be run as 
a ‘bare’ Director. Option z specifies suppression of all inessential output. A hyphen is ignored. 
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6: IMPLEMENTATION CHARACTERISTICS AND CAVEATS 
CHARACTERISTICS 
The defaults for the settable options in the present implementation of ee9 are as follows: 

* the default run mode is PROGRAM MODE 

* the default diagnostic mode is FAST MODE 

* the default diagnostic visibility generates all traces, the digital signature, and the histograms 

* the default is to run interactively; that is, with non-interactive mode disabled 

* the default elapsed time mode is MODERN TIMES MODE 

* the default time limit allows for effectively unlimited execution 

* the default time limit in non-interactive mode is 100 million instruction executions 

e the default count bounds, / and h, are O and the time limit, respectively 

e the default range bounds, a and b, are O and #17777 (8191), respectively 

* no breakpoint, watchpoint, storepoint, or core dump is pre-set 

* the shared buffer is switched by default to TP1, not GPO 

* the default graph plotter pen colour is BLACK 

e the default graph plotter pen tip is EXTRA EXTRA FINE (1 plotter step wide) 

CAVEATS 
Do not be discouraged by the length of this list; ee9 successfully runs all distributed KDF9 programs, whether surviving, 
resurrected or newly-written. 

* TSD OUTS 15 and 46 are not yet implemented. 

* There are some bogus OUTs, with numbers distinct from those of any historically valid OUT, that are implemented by ee9 
in program mode for various reasons of convenience. They may be withdrawn in future releases. 

* KDF9’s nest-depth checking caused a NOUV interrupt after the maximum or minimum depth had been transgressed. 
Presently, ee9 checks for all of these violations before the offending instruction is executed. This makes little difference in 
practice. KDF9 had ‘imprecise’ interrupts, which made recovery from a NOUV error impossible: Director could do no 
more than terminate (or perhaps restart) the offending program. The behaviour of ee9 makes debugging a bit easier. 

* There is some doubt as to the semantics of the various division instructions, particularly with respect to rounding, and 
their results on overflow and on division by zero (other than setting the overflow bit). 

e There is some doubt as to the semantics of the FLOAT and FLOATD instructions when the scale factor operand in N1 is 
outside the range -128 x N1 x +127 specified by the Manual. EE issued a library subroutine, L77, to deal with such cases, 
so it seems that the behaviour of the hardware with out of range operands was not entirely satisfactory. ee9 takes a safety 
first approach and uses the least significant 8 bits of N1 as the effective scale factor, ignoring the rest of N1. This is 
compatible with the programming of the sqrt function in the Kidsgrove Algol system. 

* The FRB and TOB orders deliver results that differ from the KDF9 hardware in unusual cases involving radix values 
greater than 31, which are stated to be illegal in the Manual, and to malfunction in the hardware documentation. 

* The all-zero syllable is documented as an invalid order, but strong evidence has come to light that the hardware actually 
treated it as a “no-op”, like DUMMY, so ee9 now does the same, identifying it in traces as DUMMYO. 

* The Standard Interface (ST) device is present as a *best guess' implementation, pending more information about it. 

* The POE and POF orders, for TP and SI, produce NULs in lieu of paper tape runout; this is suppressed in Latin-1 mode. 

* [t is assumed that the POF order for TP and SI is the same as the POE order, but that the count is multiplied by 8. 

* The POK and POL orders are fully implemented for the CP and FD devices. The PMK and PML orders are fully 
implemented for 7-track Ampex tape decks. There is considerable doubt as to the effects of the PMG, PMK, PML, POK, 
and POL orders for all other devices. 

* The CT order lets an ongoing transfer terminate normally, as if it were MANUAL; the hardware forced an immediate end. 

* [n Latin-1 mode the PIC and PID orders for FW, TR, TP and SIO copy each input byte verbatim to the least significant 8 
bits of a word; POC and POD for those devices copy the least significant 8 bits of each word verbatim to a byte of output. 

* PID and POD transfers for FW, TR, TP and SIO devices terminate after a word that has the 8-bit paper tape code for an 
EM, decimal 61, #75, in its least significant 6 bits. 

* The POC and POD orders switch FW from writing to reading after a word that has the 8-bit paper tape code for a 
semicolon, decimal 60, 774, in its least significant 6 bits. 

* ee9 cannot fully implement the semantics of 5-hole paper tape. See Appendix 2C for more details. 

* [t is assumed that the graph plotter pen tip sizes and colours are the same as those of pens presently on sale. 

* [t is assumed that the plotter command codes listed in Appendix 5, $3, p.304 of the Manual are wrong, as there is an error 
whereby 11 plotting codes are claimed but only 9 are given. The codes used by ee9 are given in Appendix 3 of this Guide. 
These have been confirmed by evidence from other computers of the era that had the same type of plotter. 
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* It is assumed that the POB and POD orders for the graph plotter have the same effect as POA and POC, respectively. The 
Manual says that the plotter responds to EM with a ‘peculiar’ pen movement, but does not end the transfer, and that 
invalid codes have ‘unpredictable’ effects. ee9 in these cases implements an arbitrary, but safe and potentially useful, 
operation: it moves the plotting position to the origin of the plotter co-ordinate system. 

* ee9 supports 4 disc drives. It is assumed that the fixed-head area of a disc drive is platter 16, seek area 0. 

* [t is assumed that a drum has 40 tracks of 8 sectors. The drum storage supported by ee9 includes 4 such drum units. 

* Many other hypotheses have been made in emulating discs and drums; it remains to be seen whether they are justified. 

* The emulation of OUT 8 by ee9 has some differences from the authentic behaviour of TSD; see Appendix 5. 

e When a program running directly uses OUT 8 to write a prompt to FWO (a ‘query’ in KDF9 parlance, including a ‘ ; ' that 
turns the write into a read), ee9 precedes the given data with ‘[q] ^; but if the transfer is a simple output message ee9 
precedes it with *[m] °. This imitates the behaviour of the non-Time Sharing (‘standard’) Director. Also, such a query 
always terminates on reading EM, but Directors insist that the EM be preceded by a full stop. 


* I/O lockouts in ee9 remain in force for the whole duration of a transfer and are cleared in toto at the end; KDF9 cleared 
the lockout of each 32-word group as soon as the transfer crossed the boundary into the next group. 

* There remain some issues related to the execution of problem programs under TSD control. 
(a) The CPU time reported by TSD may differ by about 196 from that reported by running directly under ee9. 
(b) TSD reports ludicrous execution times in the order of 800 minutes for some programs that run in a few seconds. 
(c) The coordination of a FWO transfer initiated directly by a problem program, with TSD's typing-out of its own 
messages, is not satisfactory. Programmers were strongly discouraged from direct output to FWO for this very reason. 


* Failures due to programming error can occur during a run. Some are required by the KDF9 architecture to cause a LIV 
interrupt in problem program state, and ee9 implements that. LIV interrupts are inhibited in Director state, but ee9 does 
not allow execution to continue, as that might cause unpredictable failures. Other failures were not detected by the KDF9 
hardware, but are apparent to ee9. which acts appropriately. Impossible I/O operations by Director end the run, because 
this indicates a serious malfunction. In boot mode they set the device abnormal and abandon the order; the onus is on the 
program to detect this and act accordingly —if it does not it may subsequently LIV. Failures when running a program 
directly end the run with a specific diagnostic. See Appendix 8 for a list of the various kinds of error message. 
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REFERENCES AND FURTHER READING 
Included with distributions of ee9: 


* The English Electric KDF9, The Hardware of the KDF9, The Software of the KDF9, The KDF9 and Benchmarking, The 
Purchase of a KDF9 in 1964, and The KDF9: a Bibliography 


* ee9 Users' Guide, ee9 Implementation Overview and ee9 Release History 


* Kidsgrove Code Procedures, Kidsgrove Compilation Errors, Kidsgrove Compilation Limits, Kidsgrove Compiler 
Options, Kidsgrove IO Libraries, Kidsgrove Optional Output and Kidsgrove Runtime Errors 


* README 
e Whetstone Compilation Errors, Whetstone Controller-listing, Whetstone Runtime Errors and Whetstone Translator-listing 
Available at: www. findlayw.plus.com/KDF9: 


* KDF9 Programming Manual, Publication 1002 mm ® 1001263; International Computers Ltd.; ‘the Manual’ 
e KDF9 ALGOL programming, Publication 1003 mm ® 1000565; English Electric-Leo Computers Ltd. 


SEE ALSO 
www. findlayw.plus.com/KDF9/#Emulator 


which is updated occasionally with ee9 news. 
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APPENDIX 1: ee COMMAND FUNDAMENTALS AND USAGE OPTIONS 
The emulator is invoked from the command line, thus: 
ee9 { -ss | -dd | -m[m] | -TPit | -TRit ) program file name 
where the parameters introduced by ‘-’ are optional and can be given in any number or order; m is a string that specifies a 
miscellany of options; d specifies a diagnostic execution mode; s is the initial CPU state for the KDF9 run; and tt specifies 


paper tape device character codes. Note that program file name is a path name; unlike the prog parameter of the nine shell 
command it is not by default made relative to Testing/Binary. 


The allowable state flag characters s are: 
* b: for booting into Director state, which is how operating systems such as the TSD are loaded and run 
* p: for problem program state, the default, allowing user programs to be run without a Director 
* t: for privileged program state, allowing programs to be run with OUTS serviced as in problem program state, but 
allowing privileged instructions; though inauthentic, this is useful for running ‘hardware test’ programs. 


For the diagnostic flags d, see the nine command in §1. The miscellany parameter m is described in §5.2. 


The parameters tt specify the character code to be used by either one or two paper tape punches (with —TP), or paper tape 
readers (with -TR). tt is either one or two characters, each being either k/K or 1/L, specifying KDF9 paper tape code or 
Latin-1 code respectively. If tt is one character, it refers to unit O of the type (i.e. TPO or TRO). If tt is two characters, the first 
refers to unit O and the second to unit 1 of the type. See also $3.4 and Appendix 2. The current working directory in which 
ee9 is invoked must contain files to represent the KDF9’s I/O devices. See 83. Invoking ee9 is not trivial, so there are shell 
commands to do the donkey work for you. These are described in $1. 


The ee9 distribution contains a hierarchy of directories to locate its files systematically and conveniently for the casual user. 
Testing, and its Adjuncts, Assembly, Binary, Data, Kidsgrove, Pascal, Whetstone and Workfiles 
subdirectories contain materials for KDF9 programs to use. The Adjuncts directory contains components used to run the 
Algol and Pascal compilers and the Time Sharing Director. Temporary workfiles are created in, and deleted from, 
Workfiles. However, all of these locations are defaults only, and others can be substituted if that better meets the user's 
needs. To specify alternative places shell environment variables may be exported, as follows. 


ADJUNCTS Adjuncts 

DIRECTOR Adjuncts/KKT40E007UPU 
KDF9 USERCODE Assembly 

KDF9 BINARY Binary 

KDF9 DATA Data 

KIDSGROVE Kidsgrove 

PASCAL Pascal 

WHETSTONE Whetstone 

ALGOL TEMP Workfiles 


environment variable | default path 


E.g., to nominate a directory with pathname d, for stropped Algol source files (see Appendix 12), issue the command: 
export KIDSGROVE-d 

If a KDF9 program overlays itself by means of OUT 1 (see Appendix 4), the executable is taken from the directory specified 

by KDF9 BINARY. If a program interactively requests additional data and the user gives the * @’ response (see $3.3), the file 

is looked for in the directory specified by KDF9 DATA. DIRECTOR specifies the version of TSD used by tsdnine. 

In each case the default path is used if the variable is unset (either undefined or containing the empty string). 


The defaults conform to the distributed structure when working in Testing, where most executable binaries and shell files 
are normally held. Alternatively, source code and data files can be conveniently kept together in one directory with pathname 
path, independently of the Testing hierarchy, by setting its pathname in the current shell instance, thus (note the . ): 


. workspace path 


ee9 colourizes Flexowriter output using ANSI terminal SGR escape codes. The codes used by the default ‘lite’ mode are for 
red and black text on a white background, but you can change the codes ee9 uses by exporting their values in environment 
variables as follows, where ee9 replaces the word *ESC" in the value with an ASCII Escape character. 


RED FONT SGR code for ‘red’ FW output ESC[31m [unset NULL 
BLACK FONT |SGR code for ‘black’ FW input ESC[37m  Jjunset NULL 
UNDERLINE SGR code for FW underlined text |ESC[4m unset NULL 
PLAIN FONT |SGR code for FW plain text ESC[ Om unset NULL 


The effects listed can be obtained for runs in the current shell instance with a command such as: 
. Set f codes 


where f is one of dark, lite or null. The ‘dark’ mode gives red and white text on a black background. If you prefer 
another colour scheme, set the variables as you please. 
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APPENDIX 2A: KDF9 INTERNAL CHARACTER CODES AND THEIR TRANSCRIPTIONS 
Line printer SP LF FF % ' 
Punched Cards | SP ISO:" ISO: ISO:© ISO: ISO:# % i 
Normal Case SP ISO:” LF FF HT ISO:# CS ISO:8 | CN ISO:n 
Shift Case SP ISO:" LF FF HT ISO: CS ISO:8 | CN ISO:n 
Octal code 00 01 02 03 04 05 06 07 
Line printer = ( ) £ i , / 
Punched Cards | : ( ) £ * ; / 
Normal Case ISO:& ISO:? ISO: ! ISO:$ ISO: ' ISO:S ISO:~ / 
Shift Case ISO:& ISO:? ISO:! ISO:$ ISO: ' ISO:$ ISO:~ : 
Octal code 10 11 12 13 14 15 16 17 
Line printer 0 1 2 3 4 5 6 7 
Punched Cards | 0 1 2 3 4 5 6 7 
Normal Case 0 1 2 3 4 5 6 7 
Shift Case ^ ISO:^ [ ] « - E x + 
Octal code 20 21 22 23 24 25 26 27 
Line printer 8 9 10 ISO: ; + - . 
Punched Cards | 8 9 ISO: 10 ISO: : + - 5 
Normal Case 8 9 ISO: 10 ISO: ; + - . 
Shift Case ( ) _ ISO: £ i + ISO:+ = ; 
Octal code 30 31 32 33 34 35 36 37 
Line printer A B C D E F G 
Punched Cards | ISO:@ A B C D E F G 
Normal Case ISO:@ A B C D E F G 
Shift Case ISO:@ a b c d e f g 
Octal code 40 41 42 43 44 45 46 47 
Line printer H I J K L M N O 
Punched Cards | H I J K L M N O 
Normal Case H I J K L M N O 
Shift Case h i j k l m n o 
Octal code 50 51 52 53 54 55 56 57 
Line printer P Q R S T U V W 
Punched Cards | P Q R S T U V W 
Normal Case P Q R S T U V W 
Shift Case p q T S t u V W 
Octal code 60 6l 62 63 64 65 66 67 
Line printer X Y Z 
Punched Cards | X Y Z ISO: { ISO:} — TSO: ] ISO:\ Ø 
Normal Case X Y Z ISO: { ISO:} — ISO: ISO:\ see note 
Shift Case X y Z ISO: { ISO:} — ISO: | ISO:\ see note 
Octal code 70 71 12 13 14 75 76 TI 

NOTES 


The transcription provides a Latin-1 representation for every KDF9 internal character code: 


e Code 77 is represented by Ø on punched card devices and fast storage devices invariably, on two-shift devices for 
*character mode' transfers only, and is otherwise suppressed on both input and output. 


* An empty cell indicates a code that is completely suppressed by the line printer. 


e SP is a blank space. 


e LF is Line Feed, Line Shift (LS) in KDF9 terminology; it prints as ® in NEST displays, etc. 


* FF is Form Feed, Page Change (PC) in KDF9 terminology; it prints as € in NEST displays, etc. 


e HT is Horizontal Tab; it prints as 7 in NEST displays, etc. 

* CS is Case Shift. 

* CN is Case Normal. 

e ‘y ISO:x’ indicates that x is the ISO Latin-1 transcription of the non-Latin-1 KDF9 character y. 

e ‘ISO:x’ indicates that x is the ISO Latin-1 external representation of a non-legible KDF9 character. 

* Fast storage devices (e.g. magnetic tapes) always use the Normal Case representation. 

e Except for “character mode’ output, B and ñ are acted upon by the Flexowriter, not transferred literally, so that output is 
presented in the correct case. 
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APPENDIX 2B: KDF9 PAPER TAPE CODES (WITH PARITY CHANNELS) AND THEIR TRANSCRIPTIONS 


Line printer SP LF FF % i 
Punched Cards | SP ISO:" ISO: ISO:© ISO:3 ISO:# % i 
Normal Case SP ISO:" LF FF HT ISO:# CS ISO:8 | CN ISO:n 
Shift Case SP ISO:" LF FF HT ISO: CS ISO:8 | CN ISO:n 
Paper tape 220 021 022 003 024 005 006 027 
Line printer : = ( ) £ * E / 
Punched Cards | : = ( ) £ * ; / 
Normal Case ISO:& ISO:? ISO: ! ISO:$ ISO: ' ISO:S ISO:~ / 
Shift Case ISO:& ISO:? ISO:! ISO:$ ISO: ' ISO:S ISO:~ : 
Paper tape 030 011 012 033 014 035 036 017 
Line printer 0 1 2 3 4 5 6 7 
Punched Cards | 0 1 2 3 4 5 6 7 
Normal Case 0 1 2 3 4 5 6 7 
Shift Case ^ ISO: ^ [ ] < > = x + 
Paper tape 060 041 042 063 044 065 066 047 
Line printer 8 9 10 ISO:9 + - . 
Punched Cards | 8 9 ISO: 10 ISO:2 ; t - : 
Normal Case 8 9 ISO: 19 [50:9 ; m - . 
Shift Case ( ) ISO: £ i + ISO:+ s 1 
Paper tape 050 071 072 053 074 055 056 077 
Line printer A B C D E F G 
Punched Cards | ISO:@ A B C D E F G 
Normal Case ISO:@ A B C D E F G 
Shift Case ISO:@ a b c d e f g 
Paper tape 120 101 102 123 104 125 126 107 
Line printer H I J K L M N O 
Punched Cards | H I J K L M N O 
Normal Case H I J K L M N O 
Shift Case h i j k l m n o 
Paper tape 110 131 132 113 134 115 116 137 
Line printer P Q R S T U V W 
Punched Cards | P Q R S T U V W 
Normal Case P Q R S T U V W 
Shift Case p q T S t u V W 
Paper tape 140 161 162 143 164 145 146 167 
Line printer X Y Z 
Punched Cards | X Y Z ISO: { ISO:} — TSO: ] ISO:\ Ø 
Normal Case X Y Z ISO: { ISO:} — ISO: ISO:N see note 
Shift Case X y Z ISO: { ISO:} — ISO: | ISO:\ see note 
Paper tape 170 151 152 173 154 175 176 157 
NOTE 


* Internal code 77 is represented by Ø on punched card devices and fast storage devices invariably, on two-shift devices for 
*character' mode transfers only, and is otherwise suppressed on both input and output. 

* ‘Character’ mode transfers on two-shift devices in KDF9 mode use the full 8-bit paper tape code and transfers to End 
Message terminate after the 8-bit internal code #175 (which is the Latin-1 code for ‘}’, not ‘|’). 
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APPENDIX 2C: KDF9 5-HOLE (FERRANTI) PAPER TAPE CODES 


Normal Case ISO:@ A B C D E F G 
KDF9 code 40 41 42 43 44 45 46 47 
Letters Case fs A B C D E F 
Figures Case fs 1 2 * 4 ( ) 7 
Ferranti code 00 01 02 03 04 05 06 07 
Normal Case H I J K L M N O 
KDF9 code 50 51 52 53 54 55 56 57 
Letters Case H I J K L M N O 
Figures Case 8 z - - y If sp A 
Ferranti code 10 11 12 13 14 15 16 17 
Normal Case P Q R S T U V W 
KDF9 code 60 6l 62 63 64 65 66 67 
Letters Case P Q R S T U V W 
Figures Case | 0 > > 3 = 5 6 / 
Ferranti code | 20 21 22 23 24 25 26 27 
Normal Case | X Y Z ISO: { ISO:} — ISO:| ISO:N see notes 
KDF9 code 70 71 72 73 74 75 76 71 
Letters Case X Y Z ls : ? £ er 
Figures Case x 9 + ls $ n cr er 
Ferranti code | 30 31 32 33 34 35 36 37 
NOTES 


The handling of 5-hole paper tape— in the teleprinter code of the Ferranti Pegasus, Sirius and Orion computers— is rather 
non-obvious. When a 5-hole tape was read by KDF9 the most significant bit of each input character was set to 1 by the 
hardware, adding #40 to the physical Ferranti code. On output to a 5-hole tape punch the hardware discarded that bit. This 
provided a 1-to-1 mapping and had the advantage that upper case letters got the same codes from 5-hole and 8-hole input 
tapes, namely the KDF9 native codes for those letters. ee9 cannot implement this behaviour for direct transfers, because it 
does not always know whether a paper tape device is in 5-hole mode or 8-hole mode (for example, the type of the device 
attached to a buffer can be changed dynamically by operators command to a Director) and it has no way to find out. 
Consistency demands that transfers that are notionally from 5-hole tape readers and to 5-hole tape punches work in exactly 
the same way as for 8-hole devices in ee9. 


Things are very different when a program running under Director control writes to a 5-hole punch via OUT 8 streams 50-57. 
Most KDF9 characters with codes in the ranges 700-737, and the letters A-Z, are output verbatim. Others are given special 
treatment. Director (not ee9) converts them in an attempt to preserve the appearance of a teleprinter transcription, inserting 
shift characters where necessary. Director also converts KDF9’s LS character into a fs cr If sequence. Clearly, this has the 
potential for muddle if the KDF9 data includes characters that are absent from the Ferranti teleprinter set. 


The mtp and a2b utilities (see Appendices 10 and 11) have facilities for converting from Ferranti code to Latin-1. They 
assume that the Ferranti codes are those generated by OUT 8: 


e Ferranti code 00, denoted fs, is the Figures Shift character. It switches printing to the Figures Case character set. 

e Ferranti code 33, denoted ls, is the Letters Shift character. It switches printing to the Letters Case character set. 

* Ferranti code 14 is the v character in Figures Case, but L in Letters Case. The v was treated by English Electric software 
as if it were the KDF9 19 character. It is rendered as ‘v’ by mtp and a2b. 

* Ferranti code 15, denoted /f, is the Line Feed character in Figures Case but M in Letters Case. 

* Ferranti code 16, denoted sp, is the blank space character in Figures Case but N in Letters Case. 

e Ferranti code 22 is the > character in Figures Case, but R in Letters Case. It is rendered as * ]' by mtp and a2b. 

e Ferranti code 24 is a right-arrow character in Figures Case, but T in Letters Case. It looks like, but is not, a KDF9 EM. It 
is rendered as ‘»’ by mtp and a2b. 


* Ferranti code 35 is the 7? character in Figures Case, but ? in Letters Case. This Ferranti code works like EM for 5-track 
data, since it generated the KDF9 EM internal code (775) when read by the hardware. In Figures Case it was treated by 
English Electric software as if it were an underlined EM. It is rendered as ‘n’ by mtp and a2b. 

* The KDF9 LS character has the same CR/LF effect as the ASCII Newline, but in Ferranti code there are separate CR and 
LF characters, available only in Figures Case. 

* Ferranti code 36, denoted cr above, is the Carriage Return character in Figures Case but £ in Letters Case. 

* Ferranti code 37 was used to erase paper tape characters by punching holes in all five positions of the tape frame. It is 
suppressed on output by mtp and a2b, exactly as #77 is for devices working with KDF9 codes. 
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APPENDIX 3: KDF9 GRAPH PLOTTER CODES 


Action Decimal | Octal | Binary 
None 0 #0 000000 
Step paper back 1 #1 000001 
Step paper forward 2 #2 000010 
Step pen right 4 #4 000100 
Step pen right, paper back 5 #5 000101 
Step pen right, paper forward 6 #6 000110 
Step pen left 8 #10 001000 
Step pen left, paper back 9 #11 001001 
Step pen left, paper forward 10 #12 001010 
Lower pen 16 #20 010000 
Raise pen 32 #40 100000 
NOTES 


* The command list in Appendix 6, $5, p.302 of the Manual has an obvious error whereby 11 plotting codes are claimed but 
only 9 are given, the last of them being inconsistent with the others. The present list provides the two missing codes and 
corrects the incorrect code for a step right and backwards. The codes listed here have been confirmed by the evidence of 
other computers of the era that used the same plotter; the bit positions and their interpretations correspond directly to the 
control bits in the Calcomp plotter's hardware interface. All other 6-bit character codes represent invalid plotter commands. 


APPENDIX 4: TIME SHARING DIRECTOR OUTS (SYSTEM CALLS) 
Director provides an API that is accessed by the OUT instruction with parameters in the NEST. See Table A 4.1. 
TABLE A4.1: DIRECTOR OUT PARAMETERS 


N1 N2 N3 Action 

OF Terminate this run normally. 

IE Program ... ...name | Terminate this run and overlay the program whose name is in N2-3. 

2T Time limit in seconds Restart this program. Allow it the new time limit given in N2. 

3t Return the CPU time used in N1. 
The result is given as seconds to 23 integral places. 

4t Tape label Allocate the tape deck with the reel having the 1-word label in N2. 
Return its buffer number in N1. 

54 Device type code Allocate an I/O device of the type given in N2; see Table A4.2. 
Return its buffer number in N1. 

6t Buffer number Deallocate the I/O device with buffer number in N1. 


If itis a tape deck, unload any mounted tape reel. 

(Tape decks are treated the same by OUT 6 and OUT 7 in ee9.) 
T$ Buffer number Deallocate an allocated tape deck with buffer number in N1. 
Do not unload any mounted tape reel. 


8 Control word Spool output or write to FWO. See Appendix 5. 
9, Return the time of day in N1. 

The result is given as seconds since midnight to 23 integral places. 
10 + Tape ... ...label | Allocate the tape deck with the reel having the 2-word label in N2-3. 


Return its buffer number in N1 and the ‘Tape Serial Number’ (TSN), as 
read from the label block, in N2. 


11* Control word Write core to allocated sectors of drum storage. 

12 * Control word Read allocated sectors of drum storage into core. 

13 * Number of sectors Allocate a number of drum sectors for exclusive use by this program run. 
Can be done once only per run. 

14 * Return the number of drum sectors available for allocation in N1, with the 
sign bit set if OUT 13 has already been executed. 

16 ** | Control word Write to FWO, as if by OUT 8, but with a prefix of ‘Ne '. 
See Appendix 5. 

174 Return the CPU Time in N1 and the Notional Elapsed Time in N2. 
The results are given as seconds to 23 integral places. 

4] tt | Control word Write to sector(s) in the currently selected set of disc platters. 

42 tt | Control word Read from sector(s) in the currently selected set of disc platters. 

43 $t | Oor-l Select the first (0) or the second (-1) set of disc platters for transfers. 

44 tt | Number of platters Allocate a number x 8 of disc platters. Can be done only twice per run. 

45 ft | Oor-l Deallocate all platters in the first (0) or the second (-1) set. 

47 tT Check the last FD transfer: set TR if a parity error was flagged. 
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NOTES 
+ See the Manual, §26.2. 1. 
* Obeying OUT with an empty NEST has the same effect as OUT 0. 
* OUT 1 overlays the current program with one read from external media. Its name consists of 12 Case Normal characters, 
e.g. "KMW0301--UPU". 
* OUT 2 resumes the execution of the program with a new time limit, but without its previously allocated devices. 
t See the Manual, §17.3. 
* The label for OUT 4 consists of 8 Case Normal characters. e.g. *PRINTEND". 
* The label for OUT 10 consists of a plus sign followed by 15 Case Normal characters. e.g. “+KOUTPUT/ 0023004”. 
* See the Manual, Appendix 6, 84. 
* The control word for the drum I/O OUTS is of the form Q starting sector / low core address | high core address. 
* The sectors allocated by OUT 13 are numbered from 0. 
** OUT 16 writes to the console Flexowriter in a slightly different format from OUT 8. 
The control word for OUT 16 takes the same form as for OUT 8, but only the FWO stream is supported. 
tf See the Manual, Appendix 6, $6. 
* The control word for the disc I/O OUTS is of the form Q starting sector / low core address / high core address. 
* The sectors allocated by OUT 44 are numbered from 0. 


TABLE A4.2: DEVICE TYPE CODES 


Type FW TP TR LP CR TP § CP GP SI PDP-8* | MT} 

Decimal 0 I 2 3 4 5 7 16 17 53 55 

Octal #00 #01 #02 #03 #04 #05 #07 #20 #21 #65 #67 
NOTES 


* Add 8 (#10) to codes 1-7 to reclaim a previously-relinquished device. 

§ Type 5 is for a 5-channel tape punch, using Ferranti paper tape code. 

* The PDP-8 front end for Eldon 2 and COTAN was attached to a magnetic tape buffer. 

+ A magnetic tape deck given type #67 is treated as having an unlabelled tape, which is not to be read before it is labelled. 
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APPENDIX 5: OUT 8 


Director implements an output spooling system for paper tape punches and line printers. It also administers access to the 
console Flexowriter. Up to 32 virtual output streams are provided to each running problem program; see Table A5.1. 


Stream output is written first to a designated magnetic tape. When that becomes full, or at the behest of the computer 
operator, it is rewound and the accumulated data for each stream is transferred from the tape to its associated device. A 
second magnetic tape may be designated to take output while this is happening, and the two tapes may switch róles as often 
as necessary to transfer all the outputs to their intended destinations. 


OUT 8 takes a parameter word in N2 that controls the spooling action. It is in Q store format. If the C-, I-, and M-parts are 
equal, and contain a stream number, that stream is closed. Otherwise the I-part is taken to be the starting address, a, of an 
output area and the M-part as its ending address, b. 


If b=a+ 1 and the area is laid out as follows: 


* word a+0: stream number 
e word a+1: control word in Q store format: 4095 / -1 / n 


then a device-dependent 'gap' is written to the stream; for a tape punch stream this takes the form of runout (unpunched) 
tape, of length n characters, for n / 10 inches; applied to a line printer stream it produces a PC character. 


Otherwise, and more usually, the words in address range a to b inclusive are written to the OUT 8 tape by a transfer-to-End- 


Message operation, the word at a having been overwritten by ‘red tape’ identifying the stream. 
TABLE A5.1: OUT 8 STREAMS IMPLEMENTED BY DIRECTOR 

stream number | Output Device 

#00 Flexowriter 

$10 ..17 An 8-hole paper tape punch selected by the operator 

#20 ..27 Not used 

#30 ..37 The line printer 

#40 ..47 Not used 

#50 ..57 A 5-hole paper tape punch selected by the operator 

#60 .. 67 Not used 

#10 .. T1 The line printer or a paper tape punch, at the operator’s discretion 


Special provision is made for queries, prompted responses on the Flexowriter console, which are implemented immediately, 
not deferred. In this case the parameter word in N2 must have a C-part of #100000. The output area must be laid out with a 
prompt (ending with a ‘;’ character) and be followed by an input area for the response. Various restrictions are imposed to 
preserve a tidy layout of the console’s typed log. In particular, word a is overwritten by Director with suitable format 
effectors. When running directly, an OUT 8 query always terminates on reading EM, but Director also requires the EM to be 
preceded by a period, thus :‘. |’. 

In its problem program and privileged program modes, ee9 emulates OUT 8 not by spooling, but by directly transferring the 
output to the intended destination device. Note that outputs to multiple streams intended for the same device are therefore 
interleaved by ee9, but are not interleaved by Director. In doing so ee9 is somewhat more specific than Director in its 
provision of output streams, as indicated in Table A5.2. Streams 11, 13, 15 and 17 are directed to TP1 instead of TPO, as a 
small mitigation of the interleaving issue. 


The 5-hole mode is not implemented by ee9; all paper tape output is in 8-hole mode. 


Director requires a line of output to be written in a single OUT 8 call, the line ending in a LS, PC or EM character. ee9 allows 
a line to be built up incrementally, in a series of calls to the emulated OUT 8. This behaviour was necessary to support an 
earlier version of the reconstructed I/O library in the Kidsgrove Algol run time environment. 


So far these differences between ee9 and Director have not been problematic. 


TABLE A5.2: OUT 8 STREAMS IMPLEMENTED BY ee9 
stream number | Output Device 


#00 Flexowriter 
#10, 12, 14, 16 TPO 
#11, 13,15,17 TP1 


#30 .. 37 LPO 
#50 .. 57 TP1 
#10 .. 17 LPO 
others Invalid 


The KDF9 Algol I/O procedures work on notional I/O streams, identified by decimal numbers that are made to look like 
OUT 8 octal stream numbers. For example, output to Algol stream 30 goes to OUT 8 stream #30. Algol input uses the 20 
range of stream numbers which OUT 8 does not use. 
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APPENDIX 6: DISASSEMBLED MACHINE CODE 


U format core printing attempts to present the machine code and data in the designated area in an approximation to Usercode. 
Words deemed to be data are output in a variety of formats. Instructions are shown with octal and decimal operands, or with 
Usercode symbolic operands if a symbol table has been provided. A symbol table may be obtained from a kal3 assembly 
listing using the ancillary program extract_symbols. It generates a file of Y options, which must be be copied into the 
run's settings file if symbolic disassembly is wanted from that run. For convenience, nine creates the symbol table and 
concatenates it with settings 3.txt into settings l.txt. Here is an example of the kind of output that can be 


expected. First the Usercode source text, with the Usercode symbolic names shown in boldface: 


P102V1; 
V0-200/AW1/AW5; 
V1-P[7DC]; 
013; =wo; 
SET3; =RC13; 
1; ZERO; SHLD+16 ; SHL+32; SHA-32; 
JSP100; ZERO; SHLD+6; REV; SHL+6; 
REV; SHLD-6; OR; REV; 
DC13; J1C13NZ; 
ERASE; =W4; 
SETB17; OR; =W3; 
SETB17; OR; =W2; 
V1; zW5; 
SETB70; =W1; 
vo; SET8; OUT; 
WO; -013; 
EXIT1; 
P101V3; 
V0-B2037202020; 
V1=F1000; 
V2=B3600 0000 0000 0000; 
Q13; =V3; 
STAND; DUP; ABSF; V1; xF; 
FIX; SET47; -; =C13; SHAC13; 
V3; =Q13; 
JSP100; ZERO; SHLD+30; SHL+6; 
SHLD-30; ERASE; V0; OR; 
REV; J1<Z; 
EXIT1; 
1; V2; OR; 
EXIT1; 


Here is its symbolic disassembly, again with the Usercode symbolic names shown in boldface: 


VOP102, E#2700, E1472: 
#0000000667203341 = #000 #000 #006 #335 #006 #341 = " $WO09A" 
- 115148513 = 6.155297639320E-43 = 0.000000818179394 
V1P102, E#2701, E1473: 
#7777777777777702 = #377 $377 #377 #377 #377 #302 = "00000906" 
= -62 = -1.918807060892E+28 = -0.000000000000441 
P102V1, E#2702, E1474: 
Q13; =W0; (#3334); 
SET3; =RC13; 
E#2703/4 (1475/4): 
ZERO; SHLD+16; SHL+32; SHA-32; 
JSP100; (#2742) ; (LINK=#2704/5); 
ZERO; SHLD+6; REV; SHL+6; REV; SHLD-6; OR; REV; DC13; 
JE#2703/4C13NZ; (1475); 
ERASE; =W4; (#3340); 
SETB17;(15); OR; =W3; (#3337); 
SETB17;(15); OR; =W2; (#3336); 
V1P102; (#2701); =W5; (#3341); 
SETB70; (56); =W1; (#3335); 
VOP102; (#2700); SETB10;(8); 
OUT; 
WO; (#3334); =Q13; 
EXIT1; 
DUMMYO; 


VOP101, E#2720, E1488: 
#0000002037202020 = #000 #000 #020 #175 #004 #020 = " 0.000" 
= 276628496 = 1.478725763829E-42 = 0.000001965563683 
V1P101, E#2721, E1489: 
#2127640000000000 = #105 #175 #000 #000 #000 #000 = "17T " 
- 76403173228544 = 1.000000000000E*3 = 0.542877197265625 
V2P101, E#2722, E1490: 
#3600000000000000 = £170 #000 #000 #000 #000 #000 = "- " 
= 131941395333120 = 0.000000000000E+0 = 0.937500000000000 
V3P101, E#2723, E1491: zero 
P101V3, E#2724, E1492: 
Q13; =V3P101; (#2723); 


STAND; DUP; ABSF; V1P101; (#2721); xF; FIX; SETB57;(47); -; =C13; SHAC13; V3P101; (#2723); 


JSP100; (#2742) ; (LINK=#2730/2); 


Q #000000/ #003335/ #003341 


Q 


Q #177777/ #177777/ #177702 


Q 


Q #000000/ #010175/ #002020 


Q 


Q #042575/ #000000/ #000000 


Q 


Q 


ZERO; SHLD+30; SHL+6; SHLD-30; ERASE; VOP101; (#2720); OR; REV; 


JE#2734/0LTZ; (1500); 
EXIT1; 
E#2734/0 (1500/0): 
V2P101; (#2722); OR; 
EXIT1; 


0/ 


-1/ 


0/ 


17789/ 


30720/ 


1757/ 


-1/ 


4221/ 


0/ 


0/ 


1761 


-62 


1040 


0 


Q #074000/ #000000/ #000000 
0 
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The symbol table definitions available with the Y option setting are as follows: 


Y#V n specifies the number, n, of the V stores of PO, the ‘main program’ 

YZY n specifies the number, n, of the Y stores 

YW a specifies the address, a, of WO 

YY a specifies the the address, a, of YO 

YZ a specifies the the address, a, of Z0 

Yya specifies the the address, a, of Yy0 (y stands for a capital letter; note the blank space after the Y) 


YPp @a specifies the start address, a, of routine Pp 
YPpVv @a specifies the start address, a, of routine Pp and gives the number, v, of its last V store 


When a symbol table is supplied, operand references logged in traces are also shown in symbolic form. 


An alternative to nine is the command none which creates no symbol table. Without a symbol table, ee9 analyses the 
program’s control flow and uses heuristics to determine whether a given word represents data or instructions. These do a 
good job, but cannot always be correct. Here is the non-symbolic disassembly of the same code: 


E#2700, E1472: 


#0000000667203341 = #000 #000 #006 #335 #006 #341 = " $WO9A" = Q #000000/ #003335/ #003341 
= 115148513 = 6.155297639320E-43 = 0.000000818179394 =Q 0/ 1757/ 1761 
E#2701, E1473: 
#7777777777777702 = #377 #377 #377 #377 #377 #302 = "ØØØØØØØ®" = Q £177777/ $177777/ #177702 
-62 = -1.918807060892E+28 = -0.000000000000441 =Q -1/ -1/ -62 


E#2702, E1474: 
Q13; =E#3334;(1756); 
SET3; =RC13; 
E#2703/4, E1475/4: 
ZERO; SHLD+16; SHL+32; SHA-32; 
JSE#2742/0; (1506) ; (LINK=#2704/5); 
ZERO; SHLD+6; REV; SHL+6; REV; SHLD-6; OR; REV; DC13; 
JE#2703/4C13NZ; (1475); 
ERASE; =E#3340;(1760); 
SETB17;(15); OR; =E#3337;(1759); 
SETB17;(15); OR; =E#3336; (1758); 
E#2701; (1473); =E#3341;(1761); 
SETB70; (56); =E#3335; (1757); 
E#2700;(1472); SETB10;(8); 


OUT; 
E#3334; (1756); =Q13; 
EXIT1; 
DUMMYO; 
E#2720, E1488: 
#0000002037202020 = #000 #000 #020 #175 #004 #020 = " 0.000" = Q #000000/ #010175/ #002020 
= 276628496 = 1.478725763829E-42 = 0.000001965563683 -0 0/ 4221/ 1040 
E#2721, E1489: 
#2127640000000000 = #105 #175 #000 #000 #000 #000 = "17T " = Q #042575/ #000000/ #000000 
= 76403173228544 = 1.000000000000E+3 = 0.542877197265625 = Q 17789/ 0/ 0 
E#2722, E1490: 
#3600000000000000 = #170 #000 #000 #000 #000 #000 = "- " 2 Q #074000/ #000000/ #000000 
= 131941395333120 = 0.000000000000E+0 = 0.937500000000000 = Q 30720/ 0/ 0 


E#2723, E1491: zero 
E#2724, E1492: 
Q13; =E#2723;(1491); 
STAND; DUP; ABSF; E#2721;(1489); xF; FIX; SETB57;(47); -; -C13; SHAC13; E#2723;(1491); =Q13; 
JSE#2742/0; (1506) ; (LINK=#2730/2); 
ZERO; SHLD+30; SHL+6; SHLD-30; ERASE; E#2720;(1488); OR; REV; 
JE#2734/0LTZ; (1500); 
EXIT1; 
E#2734, E1500: 
E#2722;(1490); OR; 
EXIT1; 


Here is what the first of these routines looks like with the decimal address option in force: 
E1472, E#2700: 


#0000000667203341 = #000 #000 #006 #335 #006 #341 = " $WO9A" = Q #000000/ #003335/ #003341 

= 115148513 = 6.155297639320E-43 = 0.000000818179394 =Q 0/ 1757/ 1761 
E1473, E#2701: 

#7777777777777702 = #377 #377 #377 #377 #377 #302 = "ØØØØØØØ®" = Q £177777/ $177777/ #177702 

= -62 = -1.918807060892E+28 = -0.000000000000441 =Q -1/ -1/ -62 


E1474, E2702: 
Q13; =E1756; (#3334); 
SET3; =RC13; 
E1475/4, E#2703/4: 
ZERO; SHLD+16; SHL+32; SHA-32; 
JSE1506/0; (#2742) ; (LINK=1476/5); 
ZERO; SHLD+6; REV; SHL+6; REV; SHLD-6; OR; REV; DC13; 
JE1475/4C13NZ; (#2703); 
ERASE; =E1760; (#3340); 
SET15; (#17); OR; =E1759; (#3337); 
SET15; (#17); OR; =E1758; (#3336); 
E1473; (#2701); =E1761; (#3341); 
SET56; (#70); =E1757; (#3335); 
E1472; (#2700); SET8; 
OUT; 
E1756; (#3334); =Q13; 
EXIT1; 
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APPENDIX 7: TRACING 
These examples give an indication of the types of diagnostic output that can be obtained. 
APPENDIX 7A: THE RETROSPECTIVE TRACE 


Under ND is given the NEST depth and under SD the depth of the SJNS. Under VTD are the states of the overflow and test 
registers and whether running in Director mode. For example: 
Retrospective trace of all instructions. 
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ND SD VTD CPU TIME ICR 
Ended 7223/4: OUT #0000000000000000 3 0v 1674616069 306451954 
After #23/3: ZERO #0000000000000000 = 0 4 07V 1674616056 306451953 
After #23/0: OUT #0000000000000003 3 0v 1674616054 306451952 
After #22/3: SET6 #0000000000000006 = 6 5 OV 1674616041 306451951 
After #22/1: C13 #0000000000000003 = 3 4 07V 1674616029 306451950 
After #21/5: POEQ13 Q #000003/ #000000/ #000454 3 0v 1674616024 306451949 
After #136/5: EXIT2 #20/5 3 0v 1674616005 306451948 
After #136/2: JE#137/2+; (95) #0000000000000035 3 1v 1674615986 306451947 
After #135/5: SET29; (#35) #0000000000000035 = 29 4 l1v 1674615981 306451946 
After #135/2: JE#133/5LTZ; (91) #0000000000000035 3 1v 1674615977 306451945 
After #135/1: DUP #0000000000000035 = 29 4 1V 1674615973 306451944 
After #135/0: - #0000000000000035 = 29 3 1v 1674615971 306451943 
After #134/3: SET32; (#40) #0000000000000040 = 32 4 1V 1674615970 306451942 
After #134/1: SHLD+6 #0000000000000075 = 61 3 1v 1674615959 306451941 
After #134/0: ZERO #0000000000000000 = 0 3 1v 1674615956 306451940 
After #133/5: ERASE #7500000000000000 = -13194139533312 2 1V 1674615954 306451939 
After #133/4: DUP #7500000000000000 = -13194139533312 3 1V 1674615953 306451938 
After #133/1: YOM7Q; (31488) #7500000000000000 = -13194139533312 2 1V 1674615951 306451937 
After #132/5: POBQ14 Q #000003/ #075400/ #075575 T. 52V 1674615944 306451935 
After 7132/3: PIBO15 Q #000002/ #075400/ #075575 1 1v 1674615912 306451933 
After #132/1: IM15 TO Q14 Q #000003/ #075400/ #075575 qp OV 1674615880 306451931 
After #131/5: =M15 Q #000002/ #075400/ #075575 1 TV 1674615876 306451930 
After #131/4: + #0000000000075575 = 31613 2 1v 1674615866 306451929 
After #131/2: I15 #0000000000075400 = 31488 3 1v 1674615865 306451928 
After #130/5: SET125; (#175) #0000000000000175 = 125 2 1v 1674615859 306451927 
After #130/3: =RM7 Q #000000/ #000001/ #000000 1 1v 1674615855 306451926 
After 7130/2: ZERO #0000000000000000 = 0 2 1v 1674615852 306451925 
After #130/0: =RM6 Q #000000/ #000001/ #072765 1 1v 1674615850 | 306451924 
After 7220/5: JSE#130/0; (88) 7220/5 2 1V 1674615847 306451923 
After #20/2: SETAYB1; (#72765) #0000000000072765 = 30197 2 07V 1674615836 306451922 
After #52/3: JE#20/2=2Z; (16) #0000000000000000 1 OV 1674615832 306451921 
After #52/1: SHL+24 #0000000000000000 = 0 2 OV 1674615821 306451920 
After #51/4: E0; (#0) #4013001200000000 = -139981406339072 2 OV 1674615817 306451919 
After #51/3: ERASE #0000000000000003 = 3 1 OV 1674615803 306451918 
After #51/2: ERASE #0000000000000000 = 0 2 OV 1674615802 306451917 
After #51/0: =RM2 Q #000000/ #000001/ #000000 3 0v 1674615801 306451916 
After #50/5: DUP #0000000000000000 = 0 4 07V 1674615798 306451915 
After #50/4: DUP #0000000000000000 = 0 3 0v 1674615796 306451914 
After #50/3: ZERO #0000000000000000 = 0 2 07V 1674615794 306451913 
After #160/1: EXIT1 #50/0 1 OV 1674615792 306451912 
After #157/5: POAQ14 Q #000003/ #075400/ #075400 1 1v 1674615779 | 306451911 
(etc) 
After earlier instructions, whose tracing is now lost. 
APPENDIX 7B: THE EXTERNAL TRACE OF ALL INSTRUCTION TYPES 
LOCATION ICR CPU TIME ND SD VT [N1] INSTRUCTION 
#00000/0 1 8 0 0 J#00012/0; (8) 
#00012/0 2 12 1 0 #0000000000000002 SET2 
#00012/3 3 19 2 0 #0000000000000005 SET5 
#00013/0 4 32 1 0 #0000000000000002 OUT 
#00013/3 5 35 0 0 =C15 
#00236/2 3439084 19706693 1 2V #0000000000000004 JS#00063/2;(51) 
#00063/2 3439085 19706697 2 2V #0000000000001243 M2 
#00063/4 3439086 19706699 3 2V #0000000000001243 DUP 
#00063/5 3439087 19706703 2 2V #0000000000002506 + 
#00064/0 3439088 19706705 1 2V #0000000000000004 =M3 
#00064/2 3439089 19706709 2 2V #0000000000000001 M1 
#00064/4 3439090 19706715 1 3V #0000000000000004 =LINK 
#00065/0 3439091 19706721 2 3V #0000000000000000 YA1M3; (#4713) 
(etc) 
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APPENDIX 7C: THE SINGLE-STEP TRACE 
In pause mode ee9 executes instructions one-by-one, interacting with the user at each step and presenting the values in the 
registers relevant to the instruction just obeyed: 
At #01313/4 (715/4); ICR = 182908; EL = 9111955; the instruction was 
#200:324:357, i.e. JSP40; (#1313) 
JB: #01313/4; SJNS depth: 2 


NEST: 
N1: 
#1766314631463146 = 69709037200998 = 1.999999999998E-1 = 0.495312499999997 
= Q #037546/ #063146/ #063146 = Q 16230/ 26214/ 26214 
= #077 #146 #146 #146 #146 #146 = "/V9F9F9F" 


Breakpoint: at #02357/0 (d:ebug | f:ast | t:race | p:ause or q:uit)? p 


At #02357/0 (1263/0); ICR = 182909; EL = 9111957; the instruction was 
#042, i.e. DUP 


NEST: 
N1: 
#1766314631463146 = 69709037200998 = 1.999999999998E-1 = 0.495312499999997 
= Q #037546/ #063146/ #063146 = Q 16230/ 26214/ 26214 
= #077 #146 #146 #146 #146 #146 = "/V9F9F9F" 
N2: 
#1766314631463146 = 69709037200998 = 1.999999999998E-1 = 0.495312499999997 
= Q #037546/ #063146/ #063146 = Q 16230/ 26214/ 26214 
= #077 #146 #146 #146 #146 #146 = "/V9F9F9F" 


Breakpoint: at #02357/1 (d:ebug | f:ast | t:race | p:ause or q:uit)? 


At #02357/1 (1263/1); ICR = 182910; EL = 9111961; the instruction was 
#203:104:366, i.e. JE#02366/3LEZ; (2366) 


NEST: 
N1: 
#1766314631463146 = 69709037200998 = 1.999999999998E-1 = 0.495312499999997 
= Q #037546/ #063146/ #063146 = Q 16230/ 26214/ 26214 
= #077 #146 #146 #146 #146 #146 = "/V9F9F9F" 


Breakpoint: at #02357/4 (d:ebug | f:ast | t:race | p:ause or q:uit)? 


At #02357/4 (1263/4); ICR = 182911; EL = 9111967; the instruction was 
#045, i.e. FIX 


NEST: 
N1: 
#7777777777777776 = -2 = -6.189700196427E+26 = -0.000000000000014 
= Q #177777/ #177777/ #177776 = Q -1/ -1/ -2 
= #377 #377 #377 #377 $377 #376 = "ØØØØØØØ\" 
N2: 
#3146314631463000 = 112589990684160 = 6.044629096666E+22 = 0.799999999999272 


Q #063146/ #063146/ #063000 O 26214/ 26214/ 26112 
#146 #146 #146 #146 #146 #000 = "9F9FO9F8 " 


Breakpoint: at #02357/5 (f:ast | t:race | p:ause or q:uit)? q 
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APPENDIX 7D: THE PERIPHERAL I/O EVENT TRACE 

Under CPL is given the TSD context (P, Q, R or S) if the transfer was initiated by a program, or D if initiated by Director; 
and the current priority level. Under the heading T the value of the T register is shown as Y (for 1) or N (for 0) in the case of 
an order, such as BUSY, that tests device status. S and E in the next column show the start and end of a transfer. 


Retrospective trace of peripheral I/O events. 


CPL T EL. TIME ICR 
After #4310/3:  CLOQ7 Q #072500/ #004640/ #077337 DON 2052470495 366874014 
After #2520/4:  TWEQ7 FWO Q #000000/ #000472/ #000472 DO E 2052465840 366871442 
After #2472/0:  BUSYQO FWO Q #000000/ #000000/ #000000 DO Y 2051676802 366873352 
After #1062/4: CTQ6 TR1 Q #000002/ #177777/ #000002 DON 2051672349 366872593 
After #2520/4: TWEQ7 FWO Q #000000/ #000472/ #000472 DO S 2051665840 366871441 
After #2472/0:  BUSYQO FWO Q #000000/ #000000/ #000000 DON 2051665650 366871408 
After #21/5: PGAPQ13 TPO Q #000004/ #000000/ #000454 P 0 E 2051660310 366870057 
After #1534/4: MANUALQ6 TPO Q #000004/ #000001/ #000004 DO Y 2051660310 366870512 
After #1255/2: PARQ7 TPO Q #000004/ #000000/ #000000 DON 2051660106 366870474 
After #1255/2: PARQ7 TPO buffer lockout PO 2051660106 366870473 
After #623/5: BUSYQ7 TPO Q #000004/ #000000/ #000000 DO Y 2051654372 366870467 
After #21/5: PGAPQ13 TPO Q #000004/ #000000/ #000454 P 0 S 2051652220 366870056 
After #132/5: PWEQ14 TPO Q #000004/ #066440/ #066635 P 0 E 2051660025 366869806 
After #132/3: PREQ15 TR1 Q #000002/ #066440/ #066635 P 0 E 2051651903 366869805 
After #132/5: PWEQ14 TPO Q #000004/ #066440/ #066635 P 0 S 2051650935 366869805 
After #157/5: PWO14 TPO Q #000004/ #066440/ #066440 P 0 E 2051723445 366869784 
After #132/3: PREQ15 TR1 Q #000002/ #066440/ #066635 P 0 S 2051650903 366869804 
After #157/5: PWO14 TPO Q #000004/ #066440/ #066440 P 0 S 2051650725 366869783 
After #132/3: PREQ15 TR1 Q #000002/ #066440/ #066635 P 0 E 373054471 59581364 
After #132/5: PWEQ14 TPO Q #000004/ #066440/ #066635 P 0 E 373010462 59578367 
After #132/3: PREQ15 TR1 Q #000002/ #066440/ #066635 P 0 S 372953471 59581363 
After #132/3: PREQ15 TR1 Q #000002/ #066440/ #066635 P 0 E 372945668 59578366 
After #132/5: PWEQ14 TPO Q #000004/ #066440/ #066635 P 0 S 372937742 59578366 
After #132/5: PWEQ14 TPO Q #000004/ #066440/ #066635 P 0 E 373001334 59576600 
After #132/3: PREQ15 TR1 Q #000002/ #066440/ #066635 P 0 S 372937668 59578365 
After #132/3: PREQ15 TR1 Q #000002/ #066440/ #066635 P 0 E 372936540 59576599 
After #132/5: PWEQ14 TPO Q #000004/ #066440/ #066635 P 0 S 372928614 59576599 
After #20/0: PGAPQ13 TPO Q #000004/ #000000/ #000454 P 0 E 375655473 59576588 
After #132/3: PREQ15 TR1 Q #000002/ #066440/ #066635 P 0 S 372928540 59576598 
After #20/0: PGAPQ13 TPO Q #000004/ #000000/ #000454 P 0 S 372928473 59576587 


(etc) 

After earlier interrupts, whose tracing is now lost. 

Total time waiting for unoverlapped I/O to finish = 6635ms. 
APPENDIX 7E: THE INTERRUPT TRACE 


Under CPL is the context (P, Q, R or S) and priority level of the interrupted program. In addition, the trace shows control 
returning from Director to a problem program by means of the EXITD instruction, with the BA, NOL, and instruction 
address values for the resumed program. 


Retrospective trace of interrupt requests. 


CPL EL. TIME ICR 
Ended #575/4: EDT MTO Q 8/#004335/#004336 PO 435959729 69288606 
After #76/4: EDT FWO Q 0/#005246/#005250 PO 435943366 69285714 
After #416/3: OUT 0 PO 433847319 69079602 
After #116/3: EXITD BA #004640 NOL 8191 & 7416/2 PO 433847299 69079600 
After #415/5: OUT 8 PO 433827181 69076031 
After #116/3: EXITD BA #004640 NOL 8191 @ #4430/0 PO 429984577 68459560 
After #4427/3: CLOCK 1048580 KDF9 us PO 429982227 68459073 
After #116/3: EXITD BA #004640 NOL 8191 @ #4430/0 PO 428934534 68285222 
After #4427/3: CLOCK 1048584 KDF9 us PO 428925791 68283615 
After #116/3: EXITD BA #004640 NOL 8191 @ #3153/4 PO 427877727 68109705 
After #60/5: EDT MTO Q 8/#011657/#011702 PO 427877343 68109622 
After #3153/4: LOV at #011656 (E2574) PO 427877149 68109587 
After #116/3: EXITD BA #004640 NOL 8191 @ #2056/4 PO 427877113 68109584 
After #2056/1: OUT 8 PO 427858473 68106231 
After #116/3: EXITD BA #004640 NOL 8191 @ #3270/0 PO 412965422 65759551 
After #3267/3: EDT FWO Q 0/#000472/#000472 PO 412956544 65757930 
After #116/3: EXITD BA #004640 NOL 8191 @ #3153/4 PO 412161464 65636232 
After #60/5: EDT MTO Q 8/#011657/#011702 PO 412161080 65636149 
After #3153/4: LOV at #011656 (E2574) PO 412160886 65636114 
After #116/3: EXITD BA #004640 NOL 8191 @ #2056/4 PO 412160850 65636111 
After #2472/0: EDT FWO Q 0/#000472/#000472 PO 412148327 65633868 
After #2056/1: OUT 8 PO 411606886 65632757 


After #116/3: EXITD BA #004640 NOL 8191 @ #2056/4 


PO 411352623 65591525 
After #715/0: EDT MTO Q 8/#004335/#004336 PO 411340926 65589427 
After #2472/0: EDT FWO Q 0/#000472/#000472 PO 411340010 65589283 
After #712/5: EDT MTO Q 8/#004335/#004336 PO 410541042 65587978 
After #1027/5: LOV in #066440/#066635 for TR1 PO 410532559 65586511 
After #2472/0: EDT FWO Q 0/#000472/#000472 PO 410531063 65586264 
After #457/4: EDT MTO Q 8/#004335/#004336 PO 410035534 65585510 
After #713/5: LOV MT2 is busy PO 410026286 65583901 
After #2472/0: EDT FWO Q 0/#000472/#000472 PO 410021744 65583150 
After #1045/3: EDT MTO Q 8/#003021/#003023 PO 409224283 65581808 
After #2472/0: EDT FWO Q 0/#000472/#000472 PO 409212381 65579669 
After #2056/1: OUT 8 PO 409007105 65578559 
After #116/3: EXITD BA #004640 NOL 8191 @ #3157/0 PO 408914735 65562404 
After #2472/0: EDT FWO Q 0/#000472/#000472 PO 408905390 65560684 
After #3156/3: OUT 17 PO 408408682 65559504 
After #116/3: EXITD BA #004640 NOL 8191 @ 70/0 PO 408407665 65559338 
After #2565/0: EDT TR1 Q 2/#004650/#011447 PO 408332663 65546631 
(etc) 


After earlier interrupts, whose tracing is now lost. 
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APPENDIX 7F: THE INSTRUCTION-TYPE AND INSTRUCTION-LOCUS FREQUENCY HISTOGRAMS 


Either, both or neither of these plots may be obtained, at option. The examples show two different programs. 
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Histogram of the opcodes of 3438705 executed instructions with frequency >= 0.20% 


004: xF 
012: PERM 
024: FLOAT 
027: NEG 
033: NOT 
034: xD 
036: - 
037: SIGN 
041: ZERO 
042: DUP 
043: DUPD 
045: FIX 
050: CONT 
051: REVD 
052: ERASE 
056: -* 
060: / 
062: /F 
065: REV 
066: CAB 
074: +F 
075: -F 
102: MkMqQ 
140: M-*Iq 
141: M-Iq 
151: MqTOOk 
161: SHA 
164: SHL 
166: SHLD 


170: =[R]{Q|C|I|M}q 
171: {Q|C|I|M}q 
172: =+{Q|Cc|I|M}q 


173: LINK 
174: -LINK 
206: JrNEZ 
213: Jr 
215: JSr 
217: EXIT 
221: JrEQ 
222: JrLTZ 
224: JrGTZ 
226: JrEOZ 
260: JrCqNZ 
300: EeMq 
301: -EeMq 
303: =EeMqQ 
304: SET 


Executions accounted for in the profile: 


54250 
68668 
10291 
54524 
14503 
37146 
66571 
33410 
41389 
136649 
33299 
14447 
37951 
48162 
52997 
141379 
17040 
12042 
119555 
17098 
45208 
49204 
20663 
43817 
69939 
15744 
51219 
15755 
7628 
250329 
188054 
23666 
40057 
64503 
9476 
62570 
74752 
99197 
7125 
12845 
12795 
44682 
32457 
587012 
214536 
112303 
201893 


1.58$ 
2.00$ 
0.30$ 
1.59$ 
0.42$ 
1.08$ 
1.94$ 
0.97$ 
1.20$ 
3.97$ 
0.97$ 
0.42$ 
1.10$ 
1.40$ 
1.54$ 
4.11$ 
0.50$ 
0.35$ 
3.48$ 
0.50$ 
1.31$ 
1.43$ 
0.60$ 
1.27$ 
2.03$ 
0.46$ 
1.49$ 
0.46$ 
0.22$ 
7.28% 
5.47% 
0.69% 
1.16% 
1.88% 
0.28% 
1.82% 
2.17% 
2.88% 
0.21% 
0.37% 
0.37% 
1.30% 
0.94% 
17.07% 
6.24% 
3.27% 
5.87% 


76.5% 
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Histogram of the loci of 306451954 executed instructions with frequency »- 0.50$ 


#63: 21524493 
#64: 21524493 
#65: 14349662 
#66: 7174831 
#70: 2544372 
#71: 1980726 
#72: 2592966 
#73: 3791307 
#74: 2939526 
#75: 28793967 
#76: 7174831 
#77: 11635855 
#100: 12165488 
#101: 12165488 
#102: 3041372 
#110: 3274426 
#111: 2971022 
#112: 4667583 
#113: 3073182 
#114: 6069284 
#115: 6069284 
#124: 1630169 
#125: 2220330 
#126: 2331633 
#127: 1554422 
#167: 2697092 
#171: 1992671 
#172: 1977597 
#173: 1977597 
#174: 2022819 
#204: 2697092 
#206: 2692318 
#207: 6742730 
#210: 9439822 
#211: 13485460 
#212: 6573495 
#213: 4552883 
#214: 3034642 
#215: 3034642 
#216: 4552423 
#217: 3022530 
#234: 3009498 
#235: 3022530 
#236: 4539949 
#240: 3022168 
#241: 3035562 
#242: 3371365 
#243: 2022819 
#244: 2058873 


Executions accounted for in the profile: 
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APPENDIX 8: ERROR MESSAGES FROM ee9 
The following headings introduce classes of error message. Each message may include more detailed diagnostics. 


LIV INTERRUPT 

NOUV INTERRUPT 

RESET INTERRUPT 

These are invalid operations that were detected by the KDF9 hardware. A RESET interrupt always connotes a failure, as do 
NOUV and LIV interrupts in problem programs. NOUV cannot happen in Director. 

IMPOSSIBLE I/O OPERATION 

IMPOSSIBLE I/O OPERATION IN DIRECTOR 

LIV INTERRUPT IN DIRECTOR 


These failures are caused by trying to execute an instruction that cannot be correctly interpreted. They include I/O orders 
with invalid parameters, requesting infeasible operations (such as trying to backspace a magnetic tape when it is already fully 
rewound), and miscellaneous other errors that ee9 detects and fails. Although LIV could be signalled when running Director, 
it did not interrupt. However, it is always treated by ee9 as failing, because it indicates a machine state that does not permit 
emulation to continue successfully. 

FAILURE IN OUT 


These failures are caused by OUT orders with invalid parameters, or that request impossible operations. 


FEATURE NOT YET IMPLEMENTED 
Presently, only unimplemented OUTs and unimplemented device types give rise to this error. 


THE KDF9 OPERATOR HAS MADE A MISTAKE 


These failures are caused by errors in the configuration of the emulated KDF9 that result from mistakes made in the 
invocation of ee9; e.g. by running it in the wrong working directory, so that some required file is absent. 


INVALID PAPER TAPE FILE SUPPLIED 
These failures result from the user not having set up an object program or data file correctly in KDF9 paper tape code. 


APOLOGIES FOR THIS DISMAL FAILURE 


These are failures of internal consistency checks made by ee9. They should never happen, but are handled defensively, with a 
view to debugging ee9 itself. 


OTHERS 
The following is detected during diagnostic output at the end of a run. Should never happen. 8-) 


Failure in finalize ee9... 
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APPENDIX 9: OPERATING A KDF9 WITH THE TIME SHARING DIRECTOR 

The following material draws heavily on the EE document ‘A1020 — Time Sharing Director — Mark I’, by A. Doust and M.R. 
Wetherfield, the authors of the Time Sharing Director program. 

Commands from the computer operators to Director are known as ‘TINTs’, short for Typewriter Interrupts. They are 
initiated by pressing the interrupt button on the console Flexowriter. Director responds by typing TINT; and waiting for a 
command to be input. Each such command is terminated by typing ‘.>’. With ee9, interrupt by typing CTRL-C and answer 
the prompt with RETURN. For ‘>’, shown below, type ‘|’. 


In the following, dd indicates a two-digit device (buffer) number; ff indicates a device type (see Table A4.2); p indicates a 12- 
character program name (also known as the PRN, or Program Reference Number); n is an octal number; lis a magnetic tape 
label; and s is a timesharing slot name (one of ‘P’, ‘Q’, ‘R’ or ‘S’). 


A s.2 

Terminate program in slot s, or terminate its loading. 

A st. 

Terminate program in slot s and type a basic diagnostic, showing the top of the SJNS and the NEST.. 


B sn. 
Read the octal integer n (up to 8 digits) and store its value into the less significant half of EO of s. This can be used to convey 
options to the program at run time, separately from any tape or card data. 


C dd. 

Load the magnetic tape on unit dd. Director reads the tape label, notes it, and positions the tape at the block immediately 
following, ready for allocation to a program that requests it by name, using OUT 4 or OUT 10. 

D dd. 

Unload the magnetic tape on unit dd. The tape is rewound and disengaged from the deck, ready for removal. 


E ddA.2 andE ddB.^ 
Nominate the magnetic tape loaded on unit dd for the input of A/B programs. 


F. 
Forget (used if interrupt key pressed in error). 


G.2 
Type the peripheral unit list. 


H.2 
Type a list of *wanted' tape labels. These are tapes that programs have requested, but have not yet been loaded. 


I s0.2 

Even restart for program s, i.e. make it execute the jump in the first halfword of word 0. This, and the odd restart, are for use 
when a program fails in a manner that has been anticipated, and can recover from. 

I $1.2 

Odd restart for program s , i.e. make it execute the jump in the second halfword of word 0. 


L dd/tt. 
Change the peripheral device unit dd to type tt. If tt = O, the unit is deleted from the free list. 


Mx{s?}y.9 

Output a store print in syllabic octal. x and y are both octal integers. y words are output, starting at address x: if y is omitted, 1 
is understood. If {s?} is P, Q, R or S then the base address of s is added to x. Any other separator (e.g. ‘/’) gives the absolute 
(Director) address x. 


R s.2 

Resume s (after suspension). 
S s. 

Suspend s. 


T n/w.3 
Load a B-program and give it priority level n, with a store limit of w words. Absence of w implies that the program may want 
the whole store. If the / is replaced by P the paper tape reader from which its call tape is read is pre-allocated to the program. 


A-programs are loaded on the initiative of Director, not the human operators. When the resources that are needed become 
available, Director says: 


nit P dd s 
n APIU dds 
The operator must have presented the program's call tape on the A-program input unit dd. Director reads it in and continues: 
* date time 
nsPpornsM p 
depending on whether the program itself is to be read from paper tape or magnetic tape. 
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U.» 
For each program in the machine, type its slot letter (P, Q, R or S), 12 character identifier, priority, base address, and running 
and elapsed times so far. 


V n/n'. 
Put program in priority level n into priority level n', and vice versa. 


RN magnetic tape on unit dd. Director issues the query TN/ID; to which the operator replies N//.>, e.g.: 
TN/ID;N/-*DIRECTORBINWORK.2 
Director confirms the change, e.g.: 
10L12 /Iden<+DIRECTORBINWORK>,TSN -00-0552 
WHEN THINGS GO WRONG 
If something goes wrong while reading in a program, Director types: 
nCRNP Fx 
where: CRNP means ‘Can’t Read New Program’ and x is: 
0: No paper tape reader is available for reading the A-block; this applies to B-programs only. 
1: Parity failure in the A-block. 
2: the A-block not in correct form. 
3: C-block sum check failure. 
4: Parity failure in the B-block. 
5: E2 and E3 of the B-block are not the same as the first two words of the A-block. 
6: Program's store requirement too large. 
7: Incorrect fillers for a C-block. 
8: Parity failure in a C-block. 
9: the unit specified by the A-block is not available for reading B-blocks and C-blocks. 


Program input can be terminated by giving a bogus A-block, thus inducing CRNP F2. B-program input can be terminated by 
the operator: if no reader is available, TINT A 5. causes CRNP FO, but after the A and B blocks have been read, and the 
program is waiting for core store, it causes CRNP F6. 


In the event of a problem program failing, Director types: 
ns FAILS indicator [SJNS, N1, N2 and NEST depth, where needed] 
REACT; 
This gives the operator the opportunity to abandon, or to restart the run, using A s.%,I $0.2, 0r I s1.—. The indicator is 
taken from the following list of two or three digit codes: 
S A Spurious interrupt, indicating a hardware (emulation) failure 
00L  Lock-in violation 
OON Nest or SJNS over- or under-flow 
O0T Time limit exceeded 
01 Incorrect OUT number (it is still in N1) 
02 Failure in OUT 5 
03 Failure in OUT 6 or OUT 7 
04 OUT 4 or OUT 10 requests an unavailable tape 
05 OUT 1 obeyed with less than 3 items in nest 
06 OUT 1 obeyed with incorrect program name 
07 OUT 4 specifies incorrect identifier 
11 OUT 10 specifies incorrect identifier 
71 Closing OUT 8 stream without having written anything to it 
72 Wrong terminator to output block in OUT 8 
73 Incorrect character in OUT 8 block for the Flexowriter 
74 Invalid stream number in OUT 8 
75 No magnetic tape available for OUT 8 
76 Parity failure in OUT 8 output 
77 Invalid addresses for an OUT 8 block 
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The following failures do not give the option of a restart, i.e. REACT; is not typed: 
10 CRNP failure in OUT 1 
20 Incorrect program name in OUT 2 
21 Time limit for OUT 2 absent or incorrect 
22 OUT 2 obeyed with incorrect store limit in E1 
NORMAL TERMINATION 
When a program finishes without detected failure, the following message is typed out: 
np///e/run time/n.e.t./ elapsed time 


where: run time is the CPU time used; n.e.t. is the ‘notional elapsed time’ which gives an estimate of the elapsed time would 
have been experienced had there been no delays due to multiprogramming; elapsed time is the ‘wall clock’ time since the 
program started; and e is the ‘ending number’, which gives the reason for termination, namely: 


OUTO 

OUT2 

TINTA 

CRNP in OUT 1 

any failure in OUT 2 

result of any response to REACT; 


Sd CON OV xo NS 


In the case of successful overlay by OUT 1, Director types the priority, slot and name of the new program: 
nsOUT 1 
nMp 

*DESCRIPTORS* 

Messages of the form: 


tt S dd s 


indicate that unit dd is of type tt and has current status S. For units other than magnetic tape units, when the unit is 
unallocated S is the letter U. When the unit is pre-allocated to a program or allocated to a program, S is P or A respectively. s 
indicates the program to which the unit is (pre-)allocated. When a unit is allocated to Director (e.g. for TINT M), S is the 
letter D. 


For magnetic tape units, these messages are only typed when the unit becomes loaded (L) or unloaded (U), except when the 
whole unit list is typed by TINT G). They then also include the Tape Serial Number (TSN) of the tape, e.g.: 


10L12/Iden<PRINTEND>, TSN -20-0403 
10L13/Ident<ZERO>, TSN -20-0284 
When a list is typed by TINT G, the identifiers of tapes on loaded units only are typed, and the TSN is omitted, e.g. 
10L12 PRINTEND 
10L13 ZERO 


When a unit is allocated or deallocated by a program, the descriptor is typed in the relevant column for P, Q, R or S. The only 
exceptions to this are the pre-allocation messages preceding A-program input, and messages concerning magnetic tape units. 
These are always typed in the Director column. 

WAITING FOR ... 

Messages of the form: 


SWAITING FOR TYPE tt 


mean that program s (which must in this case be a B-program) has attempted to allocate to itself a unit of type tt, but none is 
available. The operators have to decide whether or not to terminate program s (or another B-program), in order to free a 
device of type tt, or let it wait for one to be freed voluntarily. 
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APPENDIX 10: MAGNETIC TAPES IN ee9 

Magnetic tapes are represented by Ada direct access files, using the Ada.Direct IO library package, to allow selective 
overwriting of blocks. This is necessitated by the MWIPE and MGAP operations of the 1081-type tape deck. Tapes must be 
initialized (labelled) before any attempt is made to access them by a KDF9 problem program. (See RLT in Appendix 11.) 


The “write permit ring", which was a metal band inserted into the tape reel concentrically with the hub, depressed a switch to 
enable the deck's write heads. It is modelled by the file's access permission. Making the file read-only simulates an absent 
ring, allowing operations that do not change the contents of the tape, and failing those that do. 


Each tape block, and each length of erased tape, is represented by one or more "slices", a slice being a record in the direct 
access file. A slice has two components: a string and per-slice metadata. The string contains the Case Normal Latin-1 
transliteration of all or part of a KDF9 data block. In the case of an erasure slice the string reserves space for possible future 
over-writing by data, but its contents are of no significance. 


An emulated tape block is represented by a number of consecutive slices such that the total length of their contained strings is 
sufficient to encompass the data block or tape erasure. The maximum string size has been set so that blocks of 256 words (as 
used by POST), and short blocks containing OUT 8 print-line images, both have a space efficiency of better than 95%. The 
maximum block size (not slice size) is 32KW, or 256K characters, that being the maximum size of the core store. 


No attempt is made to model either interblock gaps or the erased tape extending from the Beginning of Tape Window (BTW) 
to the start of the first block of data. However interblock gaps are taken into account when estimating the elapsed time of 
magnetic tape transfers. 


Ampex 7-track tape files are recorded in exactly the same way as KDF9-native tapes, with the addition of single- slice blocks 
representing the two kinds of tape mark. They read into core as 170000000000 in the single input word. Tape marks do not 
appear in KDF9-native tapes. 


The metadata in each record is as follows. 

e Byte 0—a code indicating whether the slice represents a data block (code 'D"), a length of tape erased by the M WIPE 
operation (code ‘W’), a length erased by the MGAP operation (code ‘G’), an even parity tape mark (code ‘e’), or an odd 
parity tape mark (code ‘o’). 

e Byte 1 —a code made up as follows: 

(a) if the block is ‘LBM’ marked; i.e. if it was written by a MLWQq or MLWEQG instruction instead of the normal 
MWOQdQq and MWEQg instructions, and so responds positively to the MLBQq order: +64; 
(b) if this is the last slice of a multi-slice block: +8; and 
(c) if this is the first slice of a multi-slice block: +1. 
Byte 1 therefore has the following possible values (decimal = octal = Latin-1): 

00 000 NUL = no flags 

01 = 001 = SOH = first slice of block 

08 = 010 = BS = last slice of block 

09 = 011 = HT = only slice of block (first and last) 

64 = 100 = @ = LBM flag 

65 = 101 =A = first slice of block with LBM flag 

72 = 110-2 H = last slice of block with LBM flag 

73 = 111 = I — only (first and last) slice of block with LBM flag 

* Byte 2—the length of the string in this slice. 

This encoding makes the contents of a magnetic tape somewhat legible using the POSIX od command, but mtp usually 
offers an a more useful view. 


THE mtp UTILITY 
Convenient views of a tape file are obtainable using the mtp program. The command takes the form: 


mtp {MT|ST}{01234567}[TIPORS}{1357}{01234567}]] 


The nominated magnetic tape file is read and an interpretation of its content is written to the standard output. Any error 
messages are written to the standard error output. 


e To despool a stream from an OUT 8 tape written by TSD, append the slot letter and stream number, e.g. mtp MTOP30: 
Despooling OUT 8 stream 30 for slot P, written on 23/09/69 by WHETSTONEUPU 
N- 0 J= 0 K= 0 X1=+1.00000000 X2=-1.00000000 X3--1.00000000 X4=-1.00000000 
N= 120 J= 140 K= 120 X1=-0.06834220 X2=-0.46263766 X3=-0.72971839 X4=-1.12397907 


N= 140 J= 120 K= 120 X1=-0.05533645 X2=-0.44743656 X3=-0.71097339 X4=-1.10309806 
N=3450 J= 1 K= 1 X1=+1.00000000 X2=-1.00000000 X3=-1.00000000 X4--1.00000000 


N=2100 J= 1 K= 2 X1=+6.00000000 X2=+6.00000000 X3=-0.71097339 X4=-1.10309806 
N= 320 J= 1 K= 2 X1=+0.49040732 X2=+0.49040732 X3=+0.49039250 X4=+0.49039250 
N=8990 J= 1 K= 2 X1=+1.00000000 X2=+1.00000000 X3=+0.99993750 X4=+0.99993750 
N=6160 J= 1 K= 2 X1=+3.00000000 X2=+2.00000000 X3=+3.00000000 X4--1.10309806 
N= 0 J= 2 K= 3 X1=+1.00000000 X2=-1.00000000 X3=-1.00000000 X4=-1.00000000 
N= 930 J= 2 K= 3 X1=+0.83466552 X2=+0.83466552 X3=+0.83466552 X4=+0.83466552 


THAT TOOK 23.8 SECONDS, FOR 42.0 KWIPS 
FINISHED ENDS 0 
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* [f an OUT 8 stream is numbered in the 50-57 range it is taken to be written in Ferranti 5-hole paper tape code. In that case 
mtp attempts to emulate an original teleprinter transcription of the data. For example, this KDF9 code: 


ABCDEFGHIJKLMNOPQRSTUVWXYZ) | \Ø 
is transcribed thus in Figures Shift: 


12*4()78£--vlf ,0>»3|56/x9+.ncr 


and thus in Letters Shift: 


ABCDEFGHIJKLMNOPORSTUVWXYZ. ?£ 
Note that the @ is suppressed. 


* [f a magnetic tape contains only legible text in paper tape code, e.g. a Usercode object program as written out by the 
Kidsgrove Algol compiler, append a T to the tape deck name, e.g. mtp MT3T, to get its transcription into plain Latin-1. 


e Invoked with just the deck name, e.g. mtp MTO, it gives a slice-by-slice analysis the tape file. Each character in a data block 
is displayed using its Case Normal Latin-1 transliteration. Each slice is displayed with its record number in the direct access 
file, the KDF9 data is enclosed in «» quotes, an asterisk flags a block written with a ‘last block’ marker, and complete blocks, 
possibly consisting of several slices, are separated by blank lines. Here is the analysis of the above OUTS tape: 


TAPE LABEL TSN '-00-1478', IDENTIFIER '+KOUTPUT/0023001' 


32 


EOF 


* 


* 


«000100P"P0000010» 
«00019A&"O2QOQQPO » 
«000300& "WHETSTONEUPU 23/09/698» 
«000100&"  STR308» 
«000190&"O00O0QPO » 


«002300&"N?000000 00000 J?00000 00000 K?O00000 00000 X1?000071.0000000000000 
«X2?0000-1.0000000000000 X3?0009-1.0000000000000 X4?00090-1.000000000000000000008» 


«002300&"N?000000 1200000 J?O00000 1400000 K?00000 1200000 X1?0000-0.0683422000000 
«X2?20000-0.4626376600000 X3?0000-0.7297183900000 X4?0000-1.123979070000000000008» 


«002300&"N?000000 1400000 J?O00000 1200000 K?00000 1200000 X1?0000-0.05533645900000 
«X2?20000-0.4474365600000 X3?0000-0.7109733900000 X4?0000-1.103098060000000000008» 


«002300&"N?00000034500000 J?00000 10000 K?00000 10000 X1?00004*1.0000000000000 
«X2?0000-1.0000000000000 Xx3?00090-1.0000000000000 X4?0000-1.000000000000000000008» 


«002300&"N?00000021000000 J?00000 10000 K?00000 20000 X1?0000*6.0000000000000 
«X2?0000T6.0000000000000 X3?0000-0.7109733900000 X4?0000-1.103098060000000000008» 


«002300&"N?000000 3200000 J?00000 10000 K?00000 20000 X1?0000-0.4904073200000 
«X2?0000T0.4904073200000 X3?0000*0.4903925000000 X4?0000-0.490392500000000000008» 


«002300&"N?00000089900000 J?00000 10000 K?00000 20000 X1?000071.0000000000000 
«X2?0000T11.0000000000000 X3?000040.9999375000000 X4?0000-0.999937500000000000008» 


«002300&"N?00000061600000 J?00000 10000 K?00000 20000 X1?00007T3.0000000000000 
«X2?0000*12.0000000000000 X3?0000*3.0000000000000 X4?0000-1.103098060000000000008» 


«002300&"N?000000 0000Q J?00000 20000 K?0O0000 30000 X1?0000*1.00000000090000 
«X2?0000-1.0000000000000 X3?00090-1.0000000000000 X4?0009-1.000000000000000000008» 


«002300&"N?000000 9300000 J?00000 20000 K?0O0000 30000 X1?0000T0.8346655200000 
«X2?0000T0.8346655200000 X3?000040.8346655200000 X4?0000-0.834665520000000000008» 


«000100&"00000008» 

«000700&"THAT TOOK 000000 23.8 OOSECONDS- FOR 000 42.0 OOKWIPSOO» 
«000200& "FINISHED ENDS 0» 

«00010Z&"O000QPO » 

« } GOODDWDO » 

WIPE of 1906 erased characters 


The final ‘EOF’ is not from the tape; it is a confirmation by mtp that all of the data on the tape has been shown. 


» 


» 


» 


» 


» 


» 


» 
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APPENDIX 11: ANCILLARY PROGRAMS FOR USE WITH ee9 

This section gives specifications for the utility programs — some shell command files, some in KDF9 Usercode, and others in 
Ada 2012— that are provided with distributions of ee9 to facilitate its use. 

THE a2b UTILITY 

a2b reads data from standard input in a stated code and writes it to standard output in another form. Conversions are 


available between raw bytes and paper tape code, between paper tape code and Latin-1, and from paper tape code to a legible 
display. The command takes the form: 


a2b í(-regl-r2pl-L2pl-L2Al-p2c [FIDIMIP]lI-p2Ll-p2t!-p2ol-p2r | -F2L } 


Exactly one flag parameter must be given; it is actually case-insensitive. The effect is as follows: 


-r2p Take the input to be ‘raw’ bytes, perhaps representing KDF9 syllables; read groups of 6 to form 
48-bit words; output each such word as 8 KDF9 characters in paper tape code. 


-L2p Take the input to be 8-bit characters in Latin-1 code; transcribe them individually to KDF9 
characters in paper tape code. 


-L2A, -reg Take the input to be 8-bit characters in Latin-1 code; transcribe them to characters in 7-bit 
ASCII code that are equivalent for ka13, namely: $ for +, X for x, ~ for 9 and # for +. If the 
flag is -reg, in addition delete any CR characters. 


-p2L Take the input to be KDF9 characters in paper tape code; transcribe them individually to 8-bit 
characters in Latin-1 code; ignore NULs (runout); report parity errors. 


-p2c Take the input to be a KDF9 object program in paper tape code and output a valid call tape for 
it, using the name extracted from words 2 and 3 of the program's A block; report parity errors. If 
one of the parameters D, M, or P is given a call type of that kind is created. The parameter F (for 
file) makes a call tape for the medium specified in the A block of the program file, and this is the 
default. 


-p2t Like -p2L, but effect case shifting and ignore redundant or non-printing characters, so as to 
give a clean output text; report parity errors. 


-p20 Take the input to be KDF9 characters in paper tape code; read groups of 8 to form 48-bit words; 
output each such word in octal half/word, Q-store, syllable and character formats; report parity 
errors and incomplete words. 


-p2r Take the input to be KDF9 characters in paper tape code; read groups of 8 to form 48-bit words; 
output each such word as 6 ‘raw’ bytes; report parity errors and incomplete words. 


-F2L Take the input to be characters in Ferranti paper tape code; transcribe them to 8-bit characters 
in Latin-1 code. 


THE RLT UTILITY 

RLT is a Usercode program that reads a set of tape labels from TR1 and writes them in succession to the magnetic tape files 
MTO-MT5 and STO, having erased a gap in which to write the new label on each tape. The data given in TRI consists of one 
or more lines of text. The first 8 characters of the line give the “Tape Serial Number’ (TSN). The next 8 or 16 characters give 
the mnemonic ‘identifier’ of the tape. If the tape is intended to be a scratch work tape, its identifier must consist of 8 blank 
spaces (all zeros in KDF9 character code). A 16-character identifier must start with the character ‘+’. There must be an EM 
character (‘ | ' in ee9) after the last character of the identifier. A line starting with an EM character terminates the data. 


Here is an example, showing the sort of data that is used to label the tapes by ee9’s regression test suite: 


-00-1234WHETLIST | 
00000000 | 
-00-0552EFPBEAAG | 
77777777MS-DUMP. | 
-00-2339+KOUTPUT/0023004| 
0-00-929PRINTEND | 
0-00-777AMPEXTM4 | 


For ease of running, the command file rlt is provided to set up the environment and the ee9 mode parameters for RLT. rlt 
truncates the former contents of all of the tape files and then runs RLT in privileged program mode, so that it can access the 
physical tape buffers without having had them allocated by Director (which would require the tapes to be already labelled.) 


rlt takes the new labels from the file RLT data.txt by default. For a different set of labels, supply the name of an 
alternative file as a parameter. 
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ports [| -b | -k | -f name | 

ports (‘strop’ backwards) converts from one KDF9 Algol format to another. With a first parameter of -f and a name 
parameter, it converts from either (or both) of the whet and kalgol stropped formats (see Appendix 12) to the Flexowriter 
format needed by walgol. With a first parameter of -b or -k it converts in the opposite sense: to ‘bangs’ format, with ! 
stropping, for -b; or to ‘kwote’ format, with ' ' stropping, for -k. When going from Flexowriter format to a stropped format 
it transfers verbatim any Flexowriter symbols that are accepted by the Kidsgrove compiler. See the table below. ports reads 
from its standard input and writes the result to its standard output. 


D v O O exo e O 

! library 'library' comment librar 
!ALGOL "ALGOL ' ALGOL 
land 'and' and 

larray 'array' array 
!begin 'begin' begin 
!boolean 'boolean' boolean 
!Boolean 'Boolean' Boolean 
!comment ' comment ' comment 
!do 'do' do 

lelse 'else' else 

lend 'end' end 

leqv 'eqv' eqvv 

!EXIT ' EXIT' EXIT 
!false 'false' false 
!for 'for' for 

!goto 'goto' goto 

!to 'to' to 

!go 'go' go 

lif "it" if 

!imp 'imp' imp 
!integer ‘integer’ integer 
!KDF9 'KDF9' K DF 9 

! label 'label' label 
lnot 'not' not 

lor ‘or' or 

Lown 'own' own 
!procedure 'procedure' procedure 
!real ‘real’ real 

!step 'step' s t ep 
!string 'string' string 
!switch 'switch' switch 
!then 'then' then 

!true 'true' true 
funtil 'until' until 
!value 'value' value 
!while 'while' while 
!geor >= or > 'ge' or >=or_> > back to >= 
!leor <= or « ‘le' or <=or_< < back to <= 
{or I[ (or I _[ back to _ 

} or ] } or ] _] back to ] 
Ine or # or + 'ne'or # or t t back to + 

lup or ^ 'up' or ^ ^ back to ^ 
!divor $ or + 'div'or $ or + + back to + 

$ $ * back to $ 

* or x * or x x back to x 

-or 9 ~or 9 9 back to 9 


In this table ‘x back to y’ indicates that x is the result of transcribing the stropped-format symbol to the Flexowriter format 
and that if x is found in Flexowriter-format input, it is transcribed as y to the stropped output. An underscore followed by a 
blank is accepted as an alternative to $ in a stropped text. 
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bangs prog 
kwote prog 


bangs converts its standard input from Flexowriter format to the new Kidsgrove format in its standard output, using the 
‘bang’ (!) stropping convention for basic symbols (e.g. e n d becomes ! end). kwote does the same thing, but using the 
quoting convention (e.g. e n d becomes 'end'). The result may need some amendment to pass compilation by kalgol. 
These shell commands merely invoke ports with appropriate parameters. 


glance -ol-r|-p 

glance -o (a kind of ‘peep’) performs a range of peephole optimizations —like those of Healey and Wichmann —on the 
Usercode object programs generated by the Kidsgrove compiler. glance -r merely reformats the input, but makes no 
changes of substance. glance -p effects code optimizations for PASKAL, the KDF9 Pascal cross-compiler (see Appendix 
14). glance reads from its standard input and writes the result to its standard output. 


kidopt 
kidopt takes in a list of symbolic Kidsgrove Algol compilation options and converts them to the bit patterns used to 
transfer options to the compiler. See Appendix 12. 


st tl [store [time ] ] 

st tl amends, or creates if absent, the ST (store size) and TL (time limit) fields of a Usercode object program such as is 
generated by kalgol. If the time parameter is omitted, a value of 3000 (seconds) is used. If both are omitted, a store size of 
7680 (words) is used. st t1 reads from its standard input and writes the result to its standard output. 


The PLT utility (not yet available) 

PLT is a Usercode program that generates POST-format program library tapes that are used by the Time Sharing Director to 
hold programs that can be loaded into store at the command of an M-type call tape. If given no data PLT claims a ZERO 
(scratch) work tape, relabels it +PROGRAM/LIBRARY, and writes the sentinel blocks that structure it as an empty library. If 
given a KDF9 object program in TR1, it appends that program to the library. The command file p1t is provided to set up the 
environment and the ee9 input mode parameters correctly for PLT. See the EE KDF9 System Routine Library Manual, 
822.1, ‘Library Tape and Program Structure’, 1965. 


ee9 regr tests 

ee9 regr tests runs a comprehensive regression test of ee9. It does not include any tests of boot mode, because 
running a Director forces user interaction. This is considered a regression test because it compares its logged output with 
what is taken to be the correct output, and differences (if any) are reported. 


cr regr tests 
cr regr tests runs a comprehensive regression test of card reader and card punch emulation. 


dr regr tests 
dr tests runs a set of regression tests of drum store emulation. 


fd regr tests 
fd tests run a set of regression tests of fixed disc emulation. 


kids tests 
kids tests runs a selected set of tests of the Kidsgrove Algol compiler and runtime system. 


liv tests 
liv tests runs a comprehensive set of tests of basic CPU error-detection functionality. 


mt regr tests 
mt regr tests runs a comprehensive regression test of magnetic tape emulation. 


nouv tests 
nouv tests runs a comprehensive set of tests of basic CPU nesting store functionality. 


pasc tests 
pasc tests runs a selected set of tests of the KDF9 Pascal cross-compiler and runtime system. 


si tests 
si tests runs a set of tests for Standard Interface buffer emulation. 


walgol tests 
walgol tests runs a selected set of tests of the Whetstone Algol compiler and runtime system. 


wich tests 
wich tests runs a selected set of optimised tests of the Kidsgrove Algol compiler and runtime system. 


to 9 from 1934 

to 9 from 1934 reads the file Data/wabbit data 1900, which must contain commands for the ICT 1934 plotter, 
converts them to KDF9 plotter commands, and writes them to the file Data/wabbit data kdf9 in KDF9 8-track paper 
tape code. See ICT 1900 Technical publication 4003/C, ‘System Manual Volume X: Visual Input/Output Equipment’, 1966. 
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APPENDIX 12: WORKING WITH THE WHETSTONE AND KIDSGROVE ALGOL 60 COMPILERS 


The Algol 60 Report defines a 'reference language' that ignores the practicalities of implementation on the graphically 
impoverished computers of the 1960s. Indeed it uses symbols that are not trivially available even today, such as 10, x, +, D, 
and =. It further specifies that an implementation may work in a ‘hardware language’ that represents the reference language 
using a computer's native character set. The Whetstone (*WAlgol") and Kidsgrove ((KAlgol') hardware languages are based 
on the Friden Flexowriter character set listed in Appendix 2A. Symbols not present there are synthesized, primarily by means 
of the non-escaping underline character, so that end, for example, is prepared for input to a compiler as end and ^ as and. 


ee9 uses the Latin-1 break character as its transliteration of the Flexowriter underline, so that end appears thus: e n d. 


Another scheme, used on computers with even less flexible input than the KDF9, is the 'stropped' format: each word symbol 
is decorated with flag characters and ad hoc arrangements are made for other symbols. Many Algol systems represent end as 
‘end’, with the word enclosed in apostrophes. The Eldon 2 Teletype-based interactive system flags reserved words with an 
initial exclamation mark, thus: ! end, and this is the form I find easiest to use. 

The input routines for the resurrected Kidsgrove system allow great flexibility and convenience, with well-considered 
alternative lexical forms. The following table lists the transliterations used with ee9 for both the Whetstone and Kidsgrove 
compilers. The original Whetstone representations are accepted by the Kidsgrove compiler, but not vice versa; the Whetstone 
representations are the only ones accepted by the 1964-vintage Whetstone compiler. 


You may find it easiest to write a program in stropped format and convert it to original format, even if you only want to use 
the Whetstone compiler. See the ports commands specified in Appendix 11; it provides easy ways of converting programs 
from one format to the other. The whet command takes a program in Kidsgrove format, automatically invokes ports to 
convert it, and then uses walgol to compile and run the reformatted program. 


Algol 60 Flexowriter walgol kalgol and whet 

t t ^ ^ tup 'up' 
x x x X  * (for space in string see * ?) 
+ + + + $ !div 'div' 
10 10 S S oum 
z z t t d != Ine 'ne' 
= > E > >= lge 'ge' 
E: < = _< <= ‘le ‘le' 

=e | | 

end etc end etc |. e n d etc lend '‘end' etc 
‘string’ [string] _[string_] {string} _[string_] 
Vm Ll _[*_] {_ } {$} (note blank after _) 
a not not Inot 'not' 
A and and land ‘and’ 
v or or lor 'or' 
> im imp limp 'imp' 
= eqv equ leqv ‘eqv' 


WHETSTONE ALGOL (WALGOL) 

A selection of Algol source programs can be found in the directory Testing/Whetstone. I provide a shell command, 
walgol, in the Testing directory, that makes it easy to compile and run Algol programs using WAlgol. It expects 
programs to be in text files named with the * . a60’ suffix. The suffix is optional in a name given as parameter to the walgol 
command; if supplied, it must be correct; if omitted, it is automatically restored; so that, e.g.: 


walgol FLUID 


compiles and runs Whetstone/FLUID.a60. There is actually a lot more flexibility in the location of WAlgol source 
programs; see Appendix 1. A source program and its stream 20 data may both be kept in the same file. Alternatively, only the 
program need be held in that file, with its data being provided by the interactive input feature of ee9; see $3.3. 


Additional mode and miscellany parameters are optional and as given in $1 for the nine command. More comprehensive 
options, as described in $5, may be specified in the settings 1.txt file. If you want to specify different options for the 
program run, as opposed to its compilation, put them in the second options file, settings 2.txt. 


If either TPO or LPO is found to be non-empty at the end of a run, its content is displayed on the terminal. 


The walgol command sets up the FWO file for the Whetstone system so that you do not need to type in any responses to its 
Flexowriter prompts. If the given replies are unsuitable, change the data in FW0. for Whetstone. 

A compilation listing is produced only if the response to the compiler's OUT; prompt is an OUT 8 stream number: either 
10.| or 30. |, rather than N. |. Stream 10 is directed to TPO; stream 30 goes to LPO. You may find that the listing 
disappoints: the source code is not included. Instead the compiler outputs a table relating source line numbers and object 
code addresses, which may later be quoted in runtime error messages. The line numbers are somewhat deceptive, as they 
seem to ignore blank lines and lines before the first begin. 
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When the WAlgol object program starts, it prompts STREAM; for the number of the output stream to be used; again, reply 
10.| or 30. |. This should be the same as the stream number nominated for output in the source program. All of this is 
automated with the provided FW0. for Whetstone file, which suppresses the listing and sends output to stream 30. 


You are likely to encounter both compilation errors and execution errors. They are explained in the documents Whetstone 
Compilation Errors and Whetstone Runtime Errors. Runtime errors may be accompanied by a 'retrospective trace' which 
lists the procedures called but not yet exited, the value of any failing operand, and a source code line number. 


TO AVOID HAVING TO TYPE PROGRAMS IN THE CLUMSY FLEXOWRITER FORMAT, USE THE whet COMMAND INSTEAD. SEE $1. 


KIDSGROVE ALGOL ( KALGOL) 
The KAlgol system has been resurrected by David Holdsworth, David Huxtable (one of its original authors) and Brian 
Wichmann. It is something of a chimaera. Several of its original components are lost and have been replaced with reverse 
engineered substitutes. The object program is generated in Usercode, which needs to be assembled. For these reasons running 
the Kidsgrove system is complex, and a little flaky. Nevertheless it is well worth the effort to see what a pioneering and very 
clever compiler was able to make of an intractable language like Algol 60 six decades ago. 
A shell command, kalgol, in the Testing directory, hides this complexity and makes it easy to compile KAlgol 
programs. It has one parameter, the name of the program, taken from the directory Testing/Kidsgrove. Execution 
mode and miscellany parameters for the run of the compiler may be given in the environment variables KIDSMODE and 
KIDSMISC respectively. It is particularly useful to set KIDSMISC-w to suppress the compiler's voluminous Flexowriter 
output, and this is the default. Store size and time limits may be specified by means of the ST and TL environment variables. 
(The defaults are 30000kW and 99999sec; note that these attributes affect only runs under a Director). For example: 

ST=8192 TL-3600 kalgol FLUID 
compiles Kidsgrove/FLUID.a60,allowing the object program 8kW of core and an hour of CPU time. 
A shell command, kids, in the Testing directory, combines a call of kalgol to compile a program and a call of nine to 
run it. It has one mandatory parameter: the name of the program. Additional parameters are taken to be data, mode and 
miscellany options for the run of the object program by nine. Mode and miscellany parameters for the run of the compiler 
may be given as for kalgol. For example: 

export KIDSMODE-t; export KIDSMISC-rsw 

kids FLUID FLUID data f 
After a successful compilation with kids or kalgol the Usercode object program is left in the Assembly directory. The 
KDF9 executable is left in the Binary directory and can be run with the nine command, e.g.: 


nine FLUID FLUID data f 


There is actually a lot more flexibility in the location of KAlgol source programs, object programs, their data files, and other 
components of the Kidsgrove compilation system provided with ee9; see Appendix 1. 


Error messages are explained in the documents Kidsgrove Compilation Errors and Kidsgrove Runtime Errors. 


KAlgol procedure bodies can be written in a version of Usercode that allows access to formal parameters. This is how the 
standard functions and the I/O libraries are implemented. See the document Kidsgrove Code Procedures and, for a simple 
example, the PLOT program in Kidsgrove. 


The standard functions of Algol 60, and the KDF9 Algol I/O procedures, are incorporated into a program by means of the 
library (! library, ' library ') directive, which is placed immediately after the first begin of a program and lists the 
(source code) libraries to be included. The document Kidsgrove IO Libraries names the libraries that were originally 
provided. The table below indicates the libraries (AO through A15) that are available at the moment, and the procedures they 
contain. This is subject to occasional enhancements. 


AO the standard functions of Algol 60: sqrt, ln, exp, sin, cos, arctan, entier,abs,sign 
Al open and close; all input must come from stream 20, and all output must go to stream 30 

A4 read and read boolean (but read boolean is unlikely to work with A1 as yet) 

A5 write, output, format,write boolean 


A6 the union of Al, A4, A5, and A15 

A12 | newline,space,tab,gap 

A13 | character I/O and Algol Basic Symbol I/O 
A14 | copy text 

A15 | write text 


Itis an error to import duplicates, so that A6 should not be specified in combination with any of A1, A4, A5, and A15. 
Kidsgrove compilation options, affecting the object code, e.g. by enabling optimisation, may be given on the command line, 
thus: 

kalgol FLUID with OPTIMISER 
or by setting an environment variable, thus: 

export KIDSOPTS-"OPTIMISER" 

kalgol FLUID 


(The “with ..." syntax is a nod to the TRANSLATE command of the KDF9's POST software development system.) 
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To communicate compilation options to kalgol when using the kids command, which has an ample sufficiency of 


optional parameters, use KIDSOPTS, thus: 


export KIDSOPTS-"OPTIMISER" 
kids FLUID FLUID data 


The presently effective compilation options are as follows: 


NONE #0 | apply default options 
OPTIMISER #40 | enable global optimization 
option code meaning 


* NONE specifies the compiler’s default behaviour: an unoptimised, overflow-checking, assignment-tracing compilation with 
none of the other compile-time or run-time diagnostic outputs. 


* OPTIMISER specifies the enabling of the compiler’s global optimisations. The resulting program will probably run quite a 
bit faster. The optimiser may produce incorrect object code in difficult cases, but it is instructive to compare the Usercode 
produced with and without optimisation. Simple array-handling loops, in particular, benefit enormously. However, there is a 
restriction that the number of iterations of an optimised for .. step .. until loop must be less than 65536, because the iteration 
count is stored in the 16-bit C field of a Q store register. Optimised loops evaluate the step and until expressions only once. 
This makes a difference if the body of the loop has a potential side effect on either of them, or on the controlled variable: the 
side effect may be inoperative in optimised code, or may cause a malfunction. 


Options are given to the compiler by means of the P, ‘poke’, flag in a settings file. The kidopt program takes in the list of 
symbolic options and outputs the corresponding P flag setting. kalgol copies settings for kalgol.txt into 
settings l.txt and then appends the output from kidopt. This enables the user to set some persistent options for 
ee9’s runs of the compiler and allows them to be augmented with Kidsgrove-specific compilation options, per-run, by means 
of kidopt's output. For more information about how kalgol works, see $7 of ee9 Implementation Overview. 


(N.B. This correspondence between option bits and object code is that which is implemented in the version of the compiler 
that has been restored to working order and is now used with ee9. It is not consistent with English Electric documentation.) 


An alternative to kids is wich, which post-processes the Usercode object program from an optimised compilation with 
glance, performing peephole transformations like those suggested by Healey and Wichmann in 1971. 


The command wich f leaves the Usercode object program in a file called f-OPT.k3. Overflow checks and calls to 
diagnostic routines are removed from the program, and many longer, slower sequences are replaced by shorter, faster coding. 
The resulting program typically runs between 0% and 300% faster. However, the main reason for using wich is that it 
enables the user to see how a compiler could better exploit the KDF9 architecture. (For further steps in that direction, see the 
KDF9 Pascal cross-compiler, PASKAL.) 


SEE ALSO 
The Algol 60 language, and its usage on the KDF9 computer, are described in the following English Electric publications: 


Report On The Algorithmic Language ALGOL 60 
Ed. P. Naur; 1960. Available in: Egdon System Reference Manual, Chapter 7, 'EGDON ALGOL'. 
Publication 103 550566; English Electric-Leo—Marconi Computers Limited; 1968. 


KDF9 ALGOL Programming 
Publication 1002 mm (R) 1000565, English Electric-Leo—Marconi Computers Limited; 1969. 


The following papers describing the Kidsgrove and Whetstone systems were written by the original designers and 
implementers and constitute an invaluable historical resource: 


KIDSGROVE 


Implementation of ALGOL 60 for the English Electric KDF9 
F. G. Duncan 
Computer Journal, Vol.5, No.2, pp. 130-132; 1962. 


Input and output for ALGOL 60 on KDF9 

F. G. Duncan 

Computer Journal, Vol.5, No.4, pp. 341—344; 1963. 

A multi-pass translation scheme for ALGOL 60 

E.N. Hawkins and D.H.R. Huxtable 

Annual Review in Automatic Programming, Vol.3, pp. 163-205, Pergamon Press; 1963. 

On writing an optimizing translator for ALGOL 60 

D.H.R. Huxtable 

Introduction to System Programming , APIC Studies in Data Processing, No.4, pp. 137-155, Academic Press; 1964. 


Improving the Usercode Generated by the Kidsgrove Algol Compiler 
R. Healey and B. A. Wichmann; National Physical Laboratory CCU TM3; 1971. 


WHETSTONE 


The Whetstone KDF9 ALGOL Translator 
B. Randell 
Introduction to System Programming, APIC Studies in Data Processing, No.4, pp. 122-136, Academic Press; 1964. 


ALGOL 60 Implementation 
B. Randell and L.J. Russell 
Academic Press; 1964. 


These documents are available online, at time of writing, at www.findlayw.plus.com/KDF9. 
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APPENDIX 13: USING USERCODE 


The definitive guide to writing Usercode programs is the Manual, however some remarks about Usercode in the context of 
ee9 may be helpful. Usercode programs can be conveniently compiled using the ucc command (see $1). ucc invokes kal3, 
a modern-day Usercode compiler written by David Holdsworth as part of the effort to resurrect the Whetstone Algol system. 
As a result of its history it does not implement every feature of the Usercode language as described in the Manual; only those 
features found to be necessary for its original purpose have been implemented. Here is a list of Usercode language features 
that are not supported by ka13 and alternatives that can be used in each instance: 


Usercode ka13 alternative 


device-specific I/O mnemonics generic I/O mnemonics 
(e.g. LPQ, TWQ, etc) (e.g. POAQ) 


floating point V store constants containing 9 | scale the number explicitly 


double-length V store constants give the two words separately 


V store printer constants using * for a space | use (S) 


The input routines for ka13 can use some of the same lexical forms as the resurrected Kidsgrove Algol compiler. The 
following table lists ASCII character transliterations that you may find convenient for use with kal3, particularly if your 
computer’s editor does not readily support the Latin-1 forms: 


Original KDF9 ASCII 
Usercode alternative 
+ + % 
o EE 
10 
* + # 
7 | 
* * $ 
(for a label starting a 
new word of code) 
string quotes [ and ] _[ and _] { and } 


The ancillary program a2b has a facility to convert single characters in column 2 to those in column 3. (See Appendix 11.) 


The ee9 distribution contains a hierarchy of directories to locate its files systematically and conveniently for the casual user. 
The Assembly and Binary directories within Testing contain materials for KDF9 Usercode programs to work with. 
However, these locations are defaults only, and others can be substituted if that better meets the user’s needs. To specify 
alternative places shell environment variables maybe used, as follows: 


KDF9_USERCODE Assembly 
KDF9_BINARY Binary 
KDF9 DATA Data 


environment variable name default path 


The default path in each case is used if the environment variable is unset (either undefined or containing the empty string). 


The defaults for unset variables conform to the distributed structure when the current working directory is Testing, where 
executable binaries and shell files are normally held. See the description of the workplace command in Appendix 1. 
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APPENDIX 14: PASKAL, THE KDF9 PASCAL CROSS—COMPILER 
PASKAL runs natively on your computer and produces a KDF9 object program in the form of a Usercode text, with the aim 
of offering a better way to see the KDF9 architecture in action. If you are set up to compile and run ALGOL 60 or Usercode 
with ee9 [see §1], you can easily compile and run Pascal programs thus: 

pasc prog[datal- ] [model|- ][miscellany|- |[tt[tt]] 
where the parameters are the same as those for the kids command [see Appendix 12], except that the prog parameter 
designates the source file Pascal/prog . p. For example: 

pasc FLUID - t 


compiles Pascal/FLUID.p, generating the Usercode program Assembly/FLUID.k3 and compiling that into the 
KDF9 executable Binary/FLUID. It then runs the latter in tracing mode. 


At the moment, the data parameter is ignored and a hyphen must be supplied if any later parameter is needed. 
As for other KDF9 compilers, alternative source, Usercode and binary directories can be specified [see Appendix 1]. 


PASKAL generates very efficient code for many special cases, with the objective of reducing code size, a very important 
consideration with only 48K syllables of code available. This also shows the KDF9 architecture in a good light, which is the 
raison d'étre of PASKAL. However, being a 1-pass compiler, it cannot perform global optimizations, but is helped in making 
non-local improvements by post-processing with glance, which has access to the whole of the Usercode object program. 

A more complete description of the Pascal system is available in the PASKAL: Users' Guide, and a summary account of how 
the compiler works is given in the PASKAL: Implementation Overview. 


SEE ALSO 


PASKAL: Implementation Overview 
BILL FINDLAY, 2022 


PASKAL: Users’ Guide 
BILL FINDLAY, 2022 


These documents are available online, at time of writing, at www. findlayw.plus.com/KDF9. 
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